akm-cli 0.9.25 → 0.9.26-alpha.2

package/CHANGELOG.md

@@ -6,6 +6,45 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.9.26-alpha.2] - 2026-10-05
+
+### Added
+
+- **`akm feedback --negative` can carry an exact fix of the asset's text:**
+  `--replace "<exact current text>" --with "<corrected text>" --source "<URL,
+  command or file>"`, repeatable for several edits. akm checks at once that each
+  `--replace` text appears exactly once and that the frontmatter still parses,
+  records nothing if a check fails (so the caller can correct it and retry), and
+  queues the edit as a `feedback` proposal that shows the reason and source to
+  the reviewer. Improve has edited only an asset's frontmatter since 0.9.25, so
+  this is how a wrong fact in a note's text gets corrected: by the agent that
+  found it, with its evidence, instead of by a nightly rewrite.
+
+### Changed
+
+- **`akm feedback` help, the shipped hints and the docs no longer promise that
+  improve proposes a fix of the text from a negative reason;** they say it may
+  repair the frontmatter, and point to the exact-fix flags.
+
+## [0.9.26-alpha.1] - 2026-10-05
+
+### Changed
+
+- **Consolidate's pair judge lists what each note alone holds before it
+  classifies the pair, and akm never retires a note the judge listed anything
+  for.** The judge also reads 12,000 characters of each note instead of 2,500.
+  On 650 reviewed pairs from the owner's library, 64% of the old judge's
+  retirements lost nothing; with the lists, 92% do, and it picks the wrong
+  note to keep far less often.
+- **A confirmed duplicate retires unattended.** When the judge finds nothing
+  unique on either side, one more call asks only what the retired note holds
+  that the kept one lacks; an empty answer stages the proposal, and `triage`
+  `applyMode: "promote"` accepts it like a judged revision (it counts against
+  `maxAcceptsPerRun`, and a continuity risk keeps it for review). 109 of the
+  111 duplicates that passed in the reviewed pairs were safe to retire, and an
+  accepted retirement can be undone with `akm proposal revert`. Every other
+  retirement still waits for `akm proposal accept`.
+
 ## [0.9.25] - 2026-10-04
 
 The stable release of the 0.9.25 line: 0.9.25-alpha.1 to alpha.4, unchanged. Their

package/dist/assets/hints/cli-hints-full.md

@@ -95,7 +95,8 @@ akm workflow create ship-release               # Create a workflow asset in the
 akm lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
 akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback agents/reviewer --negative --reason "wrong framework" # Flag it for review: improve proposes a fix from the reason
+akm feedback agents/reviewer --negative --reason "wrong framework" # Flag it: lowers its ranking; improve may repair its frontmatter
+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/" # Queue an exact fix
 akm feedback memories/deployment-notes --positive # Works for memories too
 akm feedback env/prod --positive               # Records env feedback without surfacing values
 ```
@@ -103,8 +104,11 @@ akm feedback env/prod --positive               # Records env feedback without su
 Use `akm feedback` whenever an asset's content materially helps, or proves wrong,
 stale or unhelpful, so future search ranking can learn from actual usage.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
-flags the asset for review: the next improve run proposes a fix based on your
-reason, so be specific. `--positive` records that an asset helped (it raises its
+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 "<exact current text>" --with "<corrected text>" --source "<URL,
+command or file>"`, which akm checks and queues as a proposal. `--positive` records that an asset helped (it raises its
 ranking) and does not trigger a rewrite; improve no longer rewrites assets from
 positive signals or on a proactive cadence. An akm command that fails says
 nothing about the asset; don't record it as feedback.

package/dist/assets/hints/cli-hints-short.md

@@ -8,7 +8,7 @@ For any task, follow this loop:
 1. `akm curate "<task>"` — find the best matching asset
 2. `akm show <ref>` — read the schema (field names and structure)
 3. Edit the workspace file using schema field names + task-specific values from your README
-4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite); when its content was wrong, stale or unhelpful, `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it for review: the next improve run proposes a fix based on your reason, so be specific. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
+4. `akm feedback <ref> --positive` — record that the asset helped (it raises its ranking and does not trigger a rewrite); when its content was wrong, stale or unhelpful, `akm feedback <ref> --negative --reason "<what is wrong and what should change>"` flags it: the next improve run may repair its description, title or `when_to_use` from your reason, but not its text. To correct a wrong fact in the text, add the exact fix: `--replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"`. A failed akm command (e.g. `akm show` erroring) is not feedback on the asset — don't record it.
 
 For workflow tasks:
 1. `akm show workflows/<name>` — inspect the procedure before executing it
@@ -40,7 +40,8 @@ akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive                 # Record that an asset helped (ranks it higher; no rewrite)
-akm feedback <ref> --negative --reason "..."  # Flag it for review: the next improve run proposes a fix from your reason
+akm feedback <ref> --negative --reason "..."  # Flag it: lowers its ranking; improve may repair its frontmatter
+akm feedback <ref> --negative --reason "..." --replace "<exact text>" --with "<fix>" --source "<url|cmd|file>"  # Queue an exact fix of its text
 akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
 akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)

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

@@ -0,0 +1,5 @@
+You check whether deleting note X from one person's agent-memory library would lose anything. Note Y stays. List every durable claim of X that Y does not state.
+
+A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when Y says it in any wording or format, or replaces it with a newer value. It is not stated when Y is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Read X's description as part of X. Write each item as a short phrase that quotes its identifier. Use [] when Y states everything.
+
+Answer ONLY with JSON: {"missing": ["..."]}

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

@@ -1,20 +1,19 @@
-You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown.
+You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown. akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
 
-Classify the relation between them as exactly one of:
+First list what each asset has that the other lacks:
+- "onlyInA": every durable claim of A that B neither states nor updates.
+- "onlyInB": every durable claim of B that A neither states nor updates.
 
-- "duplicate": they state the same durable facts. Wording, title or formatting may differ, but neither adds a claim a reader would need that the other lacks.
-- "subsumed": one of them contains every durable claim of the other, plus more. The smaller one is redundant.
-- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value). A is now stale or wrong on that point.
+A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when the other asset says it in any wording or format. It is not stated when the other asset is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Write each item as a short phrase that quotes its identifier. Use [] when there is nothing.
+
+Then classify the relation as exactly one of:
+- "duplicate": both lists are empty.
+- "subsumed": exactly one list is empty. The asset with the empty list is redundant.
+- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
 - "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current.
-- "overlap": same subject, but each has durable claims the other lacks. Keeping both loses nothing; merging them would keep both sets of claims.
+- "overlap": same subject, and both lists have items.
 - "unrelated": different subjects or different facts that happen to share words.
 
-Rules:
-- A durable claim is a fact, decision, value, command, path, number or rule someone would act on. Ignore dates, headings, tags and phrasing.
-- Prefer "overlap" over "duplicate" when either asset has a specific detail (a number, command, file, version or condition) that the other lacks.
-- "supersedes" needs a specific claim in A that B changes. Being newer or longer is not enough.
-- "contradicts" needs two claims that cannot both be true. Different scope, project or time is not a contradiction.
-
-Set "redundant" to "A" or "B" when that asset could be removed with no loss (only for "duplicate" or "subsumed"; for "duplicate" name the less complete or older one), else null. Set "stale" to "A" when the relation is "supersedes", else null.
+Set "redundant" to the asset that could be deleted with no loss: "A" for "duplicate", the asset with the empty list for "subsumed", "A" for "supersedes"; else null. Set "stale" to "A" when the relation is "supersedes", else null.
 
-Answer ONLY with JSON: {"relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}
+Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words>"}

package/dist/assets/stash-skeleton/README.md

@@ -80,10 +80,13 @@ akm search "<query>" --type skill
 # Mark an asset as helpful (raises its ranking; does not trigger a rewrite)
 akm feedback <ref> --positive
 
-# Flag an asset for review: the next improve run proposes a fix based on your
-# reason, so be specific about what is wrong and what should change
+# Flag an asset: it ranks lower, and the next improve run may repair its
+# description, title or when_to_use from your reason
 akm feedback <ref> --negative --reason "<what is wrong and what should change>"
 
+# Correct a wrong fact in an asset's text: the exact fix is checked and queued for review
+akm feedback <ref> --negative --reason "<what is wrong>" --replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"
+
 # Capture a durable lesson or memory from the current session
 akm remember "<fact or lesson>"
 ```

package/dist/commands/feedback-cli.js

@@ -2,12 +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/.
 import fs from "node:fs";
+import { parse as yamlParse } from "yaml";
 import { defineJsonCommand, output, parseAllFlagValues } from "../cli/shared.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 { isWithin, resolveStashDir, writeFileAtomic } from "../core/common.js";
 import { FEEDBACK_FAILURE_MODES, loadConfig } from "../core/config/config.js";
 import { NotFoundError, UsageError } from "../core/errors.js";
 import { appendEvent } from "../core/events.js";
@@ -23,6 +24,7 @@ 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 { createProposal } from "./proposal/repository.js";
 // ── Tag validation ────────────────────────────────────────────────────────────
 const TAG_KEY_RE = /^[a-z_][a-z0-9_]*$/;
 function validateFeedbackTags(raw) {
@@ -185,15 +187,74 @@ function recordFeedbackUsage(indexDb, entryId, durableEntryRef, signal, metadata
     });
     return { utilityResult, rankingUpdateApplied, rankingUpdateSkippedReason };
 }
+// ── 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.');
+    }
+}
 // ── 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. `--positive` records that an asset helped\n" +
+            "(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,12 +272,24 @@ 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.",
             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.",
+        },
+        replace: {
+            type: "string",
+            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.",
         },
         "failure-mode": {
             type: "string",
@@ -262,18 +335,37 @@ export const feedbackCommand = defineJsonCommand({
                 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.
+        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) {
+            if (!args.negative) {
+                throw new UsageError("--replace, --with and --source are only for negative feedback.", "INVALID_FLAG_VALUE");
+            }
+            if (replaces.length === 0 || replaces.length !== withs.length) {
+                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()) {
             // F-3 / #384: Default requireReason is now true. Load config to allow
             // operators to opt out via feedback.requireReason: false in akm.json.
             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. " +
+                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]`);
             }
             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");
@@ -283,6 +375,7 @@ export const feedbackCommand = defineJsonCommand({
             ...(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
@@ -309,6 +402,7 @@ export const feedbackCommand = defineJsonCommand({
         let rankingUpdateApplied = false;
         let rankingUpdateSkippedReason;
         let durableRef = ref;
+        let fix;
         const db = openExistingDatabase();
         try {
             const config = loadConfig();
@@ -338,6 +432,23 @@ 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) {
+                // 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 });
+                if (!isWithin(filePath, resolved.target.source.path)) {
+                    throw new UsageError(`${itemRef} is outside bundle "${resolved.target.source.name}".`);
+                }
+                const before = fs.readFileSync(filePath, "utf8");
+                const after = applyExactReplacements(before, fixPairs, 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 } };
+            }
             const recordResult = recordFeedbackUsage(db, entryId, itemRef, signal, metadataStr);
             utilityResult = recordResult.utilityResult;
             rankingUpdateApplied = recordResult.rankingUpdateApplied;
@@ -351,6 +462,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
@@ -419,6 +540,7 @@ export const feedbackCommand = defineJsonCommand({
             rankingUpdate: rankingUpdateApplied
                 ? { applied: true }
                 : { applied: false, reason: rankingUpdateSkippedReason ?? "unknown" },
+            ...(fixProposal ? { fix: { proposalId: fixProposal.id, replacements: fixPairs.length, source: fixSource } } : {}),
             ...(appliedToResult
                 ? { appliedTo: { ref: appliedToResult.lessonRef, lessonStrength: appliedToResult.strength } }
                 : {}),

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

@@ -29,6 +29,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import consolidatePairPrompt from "../../../assets/prompts/consolidate-pair.md" with { type: "text" };
+import consolidatePairCheckPrompt from "../../../assets/prompts/consolidate-pair-check.md" with { type: "text" };
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { conceptIdFromTypeName } from "../../../core/asset/resolve-ref.js";
 import { asNonEmptyString } from "../../../core/common.js";
@@ -42,8 +43,8 @@ import { runGit } from "../../../sources/providers/git-install.js";
 import { closeDatabase, openExistingDatabase, openReadonlyExistingDatabase, } from "../../../storage/repositories/index-connection.js";
 import { getAllEntries, getEntryById } from "../../../storage/repositories/index-entries-repository.js";
 import { getNeighborsByEntryId } from "../../../storage/repositories/index-vec-repository.js";
-import { isRetireProposal } from "../../proposal/proposal-types.js";
-import { createRetireProposal, listProposalsReadOnly } from "../../proposal/repository.js";
+import { isRetireProposal, PAIR_PASS_GATE, } from "../../proposal/proposal-types.js";
+import { createRetireProposal, listProposalsReadOnly, proposalContentHash, recordGateDecision, } from "../../proposal/repository.js";
 import { isHotCapturedMemory } from "../consolidate.js";
 import { contentHash, stripFrontmatterBody } from "../content-hash.js";
 import { loadLedgerSnapshot, PAIR_PASS_LEDGER_SOURCE, recordLedgerAttempt, stripBundle } from "../ledger.js";
@@ -67,8 +68,8 @@ export const BACKFILL_FLOOR = 0.95;
 export const NEW_MATERIAL_DAYS = 7;
 /** Pairs judged per run, highest cosine first (plan §7's nightly cost budget). */
 export const MAX_PAIRS_PER_RUN = 300;
-/** Body characters sent to the judge per side (plan §4.3: bodies were truncated at this length for calibration). */
-const PAIR_BODY_TRUNCATE_CHARS = 2500;
+/** Body characters sent to the judge per side: enough for nearly every note, so a retirement is judged on the whole text. */
+const PAIR_BODY_TRUNCATE_CHARS = 12_000;
 const MS_PER_DAY = 86_400_000;
 const RELATION_LABELS = ["duplicate", "subsumed", "supersedes", "contradicts", "overlap", "unrelated"];
 const RETIRE_LABELS = new Set(["duplicate", "subsumed", "supersedes"]);
@@ -76,11 +77,14 @@ const RETIRE_LABELS = new Set(["duplicate", "subsumed", "supersedes"]);
 function isRetireLabel(label) {
     return RETIRE_LABELS.has(label);
 }
-const PAIR_JUDGE_JSON_SCHEMA = {
+/** Exported, with {@link buildPairUserPrompt}, so a replay can drive the exact judge call. */
+export const PAIR_JUDGE_JSON_SCHEMA = {
     type: "object",
-    required: ["relation", "redundant", "stale", "confidence", "reason"],
+    required: ["onlyInA", "onlyInB", "relation", "redundant", "stale", "confidence", "reason"],
     additionalProperties: false,
     properties: {
+        onlyInA: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 },
+        onlyInB: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 },
         relation: { type: "string", enum: [...RELATION_LABELS] },
         redundant: { type: ["string", "null"], enum: ["A", "B", null] },
         stale: { type: ["string", "null"], enum: ["A", null] },
@@ -88,6 +92,12 @@ const PAIR_JUDGE_JSON_SCHEMA = {
         reason: { type: "string", maxLength: 400 },
     },
 };
+const PAIR_CHECK_JSON_SCHEMA = {
+    type: "object",
+    required: ["missing"],
+    additionalProperties: false,
+    properties: { missing: { type: "array", items: { type: "string", maxLength: 200 }, maxItems: 20 } },
+};
 /** Hand-validates the judge's JSON, independent of whatever the provider's own schema enforcement did. */
 export function parsePairJudgeResponse(raw) {
     const parsed = parseEmbeddedJsonResponse(raw);
@@ -103,7 +113,16 @@ export function parsePairJudgeResponse(raw) {
         return undefined;
     const confidence = Math.max(0, Math.min(1, parsed.confidence));
     const reason = typeof parsed.reason === "string" ? parsed.reason : "";
-    return { relation: parsed.relation, redundant, confidence, reason };
+    const onlyInA = claimList(parsed.onlyInA);
+    const onlyInB = claimList(parsed.onlyInB);
+    if (!onlyInA || !onlyInB)
+        return undefined;
+    return { onlyInA, onlyInB, relation: parsed.relation, redundant, confidence, reason };
+}
+function claimList(value) {
+    if (!Array.isArray(value) || !value.every((v) => typeof v === "string"))
+        return undefined;
+    return value.map((v) => v.trim()).filter(Boolean);
 }
 function isFlatName(name) {
     return !name.includes("/");
@@ -445,7 +464,7 @@ function orderByAge(x, y) {
     return xIsOlder ? { older: x, newer: y } : { older: y, newer: x };
 }
 /** The user message: dates decide "A (older)" / "B (newer)" (plan Appendix A), matching the calibration sample's own ordering. */
-function buildPairUserPrompt(older, newer) {
+export function buildPairUserPrompt(older, newer) {
     return [...sideSection("A (older)", older), ...sideSection("B (newer)", newer)].join("\n");
 }
 /** The tombstone-vocabulary reason a judge label maps to (`supersedes` -> `superseded`; the rest unchanged). */
@@ -456,19 +475,59 @@ export function tombstoneReason(label) {
  * The calibrated outcome table (owner grades, replacing plan §5.2's
  * "shorter body" rule): `duplicate`/`supersedes` keep the newer copy;
  * `subsumed` keeps the side the judge did NOT name `redundant` (no proposal
- * if that pointer is missing or invalid).
+ * if that pointer is missing or invalid). A side is retired only when the
+ * judge listed nothing that it alone holds.
  */
-export function decideRetirement(label, redundant, older, newer) {
+export function decideRetirement(label, redundant, older, newer, only) {
+    let decision;
     if (label === "duplicate" || label === "supersedes")
-        return { retired: older, successor: newer };
-    if (label === "subsumed") {
-        if (redundant === "A")
-            return { retired: older, successor: newer };
-        if (redundant === "B")
-            return { retired: newer, successor: older };
-        return undefined; // the judge's pointer is missing or invalid — no proposal
-    }
-    return undefined;
+        decision = { retired: older, successor: newer };
+    else if (label === "subsumed" && redundant === "A")
+        decision = { retired: older, successor: newer };
+    else if (label === "subsumed" && redundant === "B")
+        decision = { retired: newer, successor: older };
+    if (!decision)
+        return undefined;
+    return (decision.retired === older ? only.onlyInA : only.onlyInB).length === 0 ? decision : undefined;
+}
+function checkSection(label, side) {
+    return [
+        `Note ${label}:`,
+        `Ref: ${side.asset.ref}`,
+        `Description: ${asNonEmptyString(side.frontmatter.description) ?? "(none)"}`,
+        "Content:",
+        "```",
+        stripFrontmatterBody(side.raw).slice(0, PAIR_BODY_TRUNCATE_CHARS),
+        "```",
+        "",
+    ].join("\n");
+}
+/**
+ * The second look a duplicate gets before it may retire unattended: one call
+ * that asks only what the retired note holds that the kept one lacks. True
+ * only on a clean, empty answer (it caught 2 of 4 duplicates the judge got
+ * wrong, and held back none of 109 right ones).
+ */
+async function confirmNothingLost(ctx, retired, successor) {
+    const outcome = await callStage({
+        feature: "memory_consolidation",
+        runner: ctx.llmRunner,
+        system: consolidatePairCheckPrompt,
+        prompt: `${checkSection("X (to delete)", retired)}\n${checkSection("Y (kept)", successor)}`,
+        gate: { config: ctx.config, enabled: true },
+        request: {
+            responseSchema: PAIR_CHECK_JSON_SCHEMA,
+            enableThinking: false,
+            ...(Object.hasOwn(ctx.llmRunner, "timeoutMs") ? { timeoutMs: ctx.llmRunner.timeoutMs } : {}),
+            signal: ctx.opts.signal,
+            ...(ctx.chat ? { chat: ctx.chat } : {}),
+        },
+        parse: (raw) => claimList(parseEmbeddedJsonResponse(raw)?.missing),
+        ...(ctx.opts.onNotices ? { onNotices: ctx.opts.onNotices } : {}),
+    });
+    if (!outcome.ok)
+        return false;
+    return claimList(parseEmbeddedJsonResponse(outcome.raw)?.missing)?.length === 0;
 }
 /**
  * One pair: judge it, then (for a retire class) apply the guards and mint
@@ -519,7 +578,7 @@ async function judgeOne(ctx, candidate) {
         return { failed: false }; // counted; stays human — no proposal, no belief write
     if (!isRetireLabel(verdict.relation))
         return { failed: false }; // overlap / unrelated: judged_no_action
-    const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer);
+    const decision = decideRetirement(verdict.relation, verdict.redundant, older, newer, verdict);
     if (!decision)
         return { failed: false };
     const { retired, successor } = decision;
@@ -599,6 +658,21 @@ async function judgeOne(ctx, candidate) {
         }, ctx.opts.proposalsCtx);
         ctx.retired.push(proposal.id);
         ctx.perInitiatorProposed.add(candidate.initiator.ref);
+        // A duplicate with nothing unique on either side, confirmed by a second
+        // look, is the one class that retires unattended (109 of 111 safe on the
+        // owner's reviewed pairs, 2026-10-04): the triage drain accepts it under
+        // its usual applyMode. Every other retirement waits for a person.
+        if (verdict.relation === "duplicate" &&
+            verdict.onlyInA.length + verdict.onlyInB.length === 0 &&
+            !continuityRisk &&
+            (await confirmNothingLost(ctx, retired, successor))) {
+            recordGateDecision(ctx.stashDir, proposal.id, {
+                outcome: "staged",
+                reason: "duplicate",
+                gate: PAIR_PASS_GATE,
+                contentHash: proposalContentHash(proposal),
+            }, ctx.opts.proposalsCtx);
+        }
         return { failed: false };
     }
     catch (error) {

package/dist/commands/proposal/drain.js

@@ -30,7 +30,7 @@ import { buildExecution, resolveExecution } from "../../integrations/agent/execu
 import { assertRunnerCredentials, runExecution, } from "../../integrations/agent/runner-dispatch.js";
 import { errMessage, noticeSet } from "../improve/stage.js";
 import { akmProposalAccept, akmProposalReject } from "./proposal.js";
-import { isRetireProposal, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
+import { isRetireProposal, PAIR_PASS_GATE, STALE_TARGET_GATE_REASON } from "./proposal-types.js";
 import { listProposals, listProposalsReadOnly, preflightProposalPromotion, proposalContent, proposalContentHash, readFreshProposalTarget, recordGateDecision, } from "./repository.js";
 /** The gate label on every decision the drain records. */
 const DRAIN_GATE = "triage";
@@ -313,13 +313,21 @@ export async function drainProposals(opts, promoteFn = akmProposalAccept, reject
     const accepts = [];
     const empties = [];
     for (const proposal of pending) {
-        // A consolidate pair-pass `retire` proposal is never auto-decided here,
-        // whatever `applyMode` says (alpha.9 brief §A "Review"; spec §25.6):
-        // untouched, still pending, waiting for a direct `akm proposal accept`.
-        // Checked before isEmptyDiff, which reads proposalContent() and has
-        // nothing meaningful to read on a delete-primary change anyway.
-        if (isRetireProposal(proposal))
+        // A consolidate pair-pass `retire` proposal is auto-accepted only when the
+        // pair judge staged it as a duplicate with nothing unique on either side
+        // (spec §25.9, equivalent content); every other one waits for a direct
+        // `akm proposal accept` (spec §25.6). Checked before isEmptyDiff, which
+        // has nothing meaningful to read on a delete-primary change.
+        if (isRetireProposal(proposal)) {
+            const staged = proposal.gateDecision;
+            if (staged?.outcome === "staged" &&
+                staged.gate === PAIR_PASS_GATE &&
+                staged.contentHash === proposalContentHash(proposal) &&
+                !proposal.retirement?.continuityRisk) {
+                accepts.push({ id: proposal.id, reason: "duplicate" });
+            }
             continue;
+        }
         const decision = proposal.gateDecision;
         // Another gate's rejection stands, and another gate's deferral is a
         // generating stage's hand-off to a person: it is left for that person.

package/dist/commands/proposal/proposal-types.js

@@ -53,6 +53,8 @@ export function isRetireProposal(proposal) {
 }
 /** A promote refused because the target changed after mint (STALE, R20) — not a merit judgement. */
 export const STALE_TARGET_GATE_REASON = "stale-target";
+/** The gate on a retire proposal the triage drain may accept unattended: a pair-judged duplicate. */
+export const PAIR_PASS_GATE = "consolidate-pair";
 export const EXPIRED_GATE_REASON = "expired";
 export const ASSET_MISSING_GATE_REASON = "asset-missing";
 const PROCEDURAL_GATE_REASONS = new Set([

package/dist/commands/proposal/repository.js

@@ -287,6 +287,7 @@ export function createProposal(stashDir, input, ctx) {
             ...(input.eligibilitySource !== undefined ? { eligibilitySource: input.eligibilitySource } : {}),
             ...(input.promotionSource !== undefined ? { promotionSource: input.promotionSource } : {}),
             ...(input.promotionSourceHash !== undefined ? { promotionSourceHash: input.promotionSourceHash } : {}),
+            ...(input.feedback !== undefined ? { feedback: input.feedback } : {}),
         };
         upsertProposal(db, proposal, stashDir);
         for (const ref of input.attemptedRefs ?? [normalizedRef]) {

package/dist/output/shapes/helpers.js

@@ -85,6 +85,7 @@ export function shapeProposalEntry(entry, detail) {
             "updatedAt",
             "confidence",
             "gateDecision",
+            "feedback",
             "review",
             "reviewHistory",
             "retirement",
@@ -101,6 +102,7 @@ export function shapeProposalEntry(entry, detail) {
         "updatedAt",
         "confidence",
         "gateDecision",
+        "feedback",
         "payload",
         "review",
         "reviewHistory",

package/dist/output/text/proposal-format.js

@@ -183,6 +183,11 @@ export function formatProposalShowPlain(r) {
         if (gate.decidedAt)
             lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
     }
+    const fix = p.feedback;
+    if (fix) {
+        lines.push(`feedback.reason: ${String(fix.reason)}`);
+        lines.push(`feedback.source: ${String(fix.source)}`);
+    }
     const review = p.review;
     if (review) {
         lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

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

@@ -28539,6 +28539,7 @@ function shapeProposalEntry(entry, detail) {
       "updatedAt",
       "confidence",
       "gateDecision",
+      "feedback",
       "review",
       "reviewHistory",
       "retirement"
@@ -28554,6 +28555,7 @@ function shapeProposalEntry(entry, detail) {
     "updatedAt",
     "confidence",
     "gateDecision",
+    "feedback",
     "payload",
     "review",
     "reviewHistory",
@@ -30491,6 +30493,11 @@ function formatProposalShowPlain(r) {
     if (gate.decidedAt)
       lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
   }
+  const fix = p.feedback;
+  if (fix) {
+    lines.push(`feedback.reason: ${String(fix.reason)}`);
+    lines.push(`feedback.source: ${String(fix.source)}`);
+  }
   const review = p.review;
   if (review) {
     lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

package/dist/scripts/akm-migrate.js

@@ -27867,6 +27867,7 @@ function shapeProposalEntry(entry, detail) {
       "updatedAt",
       "confidence",
       "gateDecision",
+      "feedback",
       "review",
       "reviewHistory",
       "retirement"
@@ -27882,6 +27883,7 @@ function shapeProposalEntry(entry, detail) {
     "updatedAt",
     "confidence",
     "gateDecision",
+    "feedback",
     "payload",
     "review",
     "reviewHistory",
@@ -29819,6 +29821,11 @@ function formatProposalShowPlain(r) {
     if (gate.decidedAt)
       lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
   }
+  const fix = p.feedback;
+  if (fix) {
+    lines.push(`feedback.reason: ${String(fix.reason)}`);
+    lines.push(`feedback.source: ${String(fix.source)}`);
+  }
   const review = p.review;
   if (review) {
     lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);

package/dist/storage/repositories/proposals-repository.js

@@ -171,6 +171,12 @@ function validatePresentMetadata(meta) {
             }
         }
     }
+    if (Object.hasOwn(meta, "feedback")) {
+        const fix = meta.feedback;
+        if (!isRecord(fix) || typeof fix.reason !== "string" || typeof fix.source !== "string") {
+            invalidPresentField("feedback");
+        }
+    }
     if (Object.hasOwn(meta, "acceptedTarget")) {
         const target = meta.acceptedTarget;
         if (typeof target !== "object" ||
@@ -293,6 +299,7 @@ export function proposalRowToProposal(row) {
         ...(meta.reviewHistory !== undefined ? { reviewHistory: meta.reviewHistory } : {}),
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
+        ...(meta.feedback !== undefined ? { feedback: meta.feedback } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
         ...(meta.acceptedTarget !== undefined ? { acceptedTarget: meta.acceptedTarget } : {}),
         ...(typeof meta.eligibilitySource === "string"
@@ -359,6 +366,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.confidence = proposal.confidence;
     if (proposal.gateDecision !== undefined)
         metaObj.gateDecision = proposal.gateDecision;
+    if (proposal.feedback !== undefined)
+        metaObj.feedback = proposal.feedback;
     if (proposal.backupContent !== undefined)
         metaObj.backupContent = proposal.backupContent;
     if (proposal.acceptedTarget !== undefined)

package/docs/reference/cli.md

@@ -1589,9 +1589,14 @@ preserves it byte-for-byte.
 
 Record positive or negative feedback for any indexed bundle asset.
 `akm feedback <ref> --negative --reason "<what is wrong and what should change>"`
-flags the asset for review: the next improve run proposes a fix based on your
-reason, so be specific. `--positive` records that an asset helped (it raises
-its ranking) and does not trigger a rewrite. Both signals update the asset's
+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.
 
 ```sh
@@ -1602,13 +1607,17 @@ 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 "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/"
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--positive` | Record that an asset helped: it raises its ranking and does not trigger a rewrite |
-| `--negative` | Flag the asset for review: the next improve run proposes a fix based on `--reason`, so be specific |
-| `--reason` | What is wrong with the asset's content and what should change; not for `akm` command errors. Attached to the feedback event and read by the next improve run's fix proposal (required for negative feedback by default) |
+| `--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`) |
+| `--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. |
 | `--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. |
@@ -3097,8 +3106,8 @@ akm proposal drain --strategy default --promote -y  # Read the triage block from
 
 `akm feedback` accepts an optional `--reason <text>` flag whose value is
 forwarded into feedback metadata and consumed by improve/distill proposal
-prompts. Negative feedback requires a reason by default: the next improve run
-proposes a fix from it, so say what is wrong and what should change.
+prompts. Negative feedback requires a reason by default: say what is wrong and
+what should change.
 
 Write the reason about the asset's content. Reflect treats it as an unverified
 report to investigate, not a fact to insert, and is told to leave the section

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` |
+| `feedback` | `akm feedback <ref>` | `signal` (positive/negative), `reason`, `failureMode`, `tags`, `fix` (`source` and the number of replacements, when an exact fix was attached) |
 | `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) |

package/package.json

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