akm-cli 0.9.26 → 0.9.27-alpha.2

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.",
+                    },
                 },
             },
         },
@@ -250,6 +260,39 @@ function loadPendingConsolidateProposalHashes(stashDir, proposalsCtx) {
     }
     return hashes;
 }
+/**
+ * Rejections decided before this are not a verdict on the memory's text: the
+ * 2026-08-02 and 2026-08-18 bulk audits rejected hundreds of promotions
+ * wholesale, and holding their bodies would skip good memories for good.
+ */
+const REJECTED_BODY_HOLD_FROM = "2026-09-29";
+/**
+ * Body hashes of the memories whose promotion was rejected on review. A
+ * proposal minted with `promotionSourceHash` names the memory's raw body; an
+ * older one is hashed from its own body, which is the memory's unless
+ * sanitization changed it.
+ */
+function loadRejectedPromotionBodyHashes(stashDir, proposalsCtx) {
+    const hashes = new Set();
+    try {
+        for (const p of listProposalsReadOnly(stashDir, { status: "rejected", includeArchive: true }, proposalsCtx)) {
+            if (p.source !== "consolidate")
+                continue;
+            if ((p.review?.decidedAt ?? p.updatedAt) < REJECTED_BODY_HOLD_FROM)
+                continue;
+            try {
+                hashes.add(p.promotionSourceHash ?? contentHash(proposalContent(p), "body"));
+            }
+            catch {
+                // A malformed payload cannot hold a memory.
+            }
+        }
+    }
+    catch {
+        // Best-effort: a failed read never blocks judging.
+    }
+    return hashes;
+}
 /**
  * Body hashes of the live knowledge assets, read from disk (the index may lag
  * a just-written asset), so an accepted promotion is not proposed again.
@@ -459,6 +502,18 @@ export function inspectConsolidationPool(opts, stashDir, warnings, existingKnowl
             return !isLedgerBlocked(row, nowIso, changedAt);
         });
     }
+    // A memory whose text a reviewer already rejected as a promotion waits for an edit, whatever it is called.
+    const rejectedBodies = loadRejectedPromotionBodyHashes(stashDir, opts.proposalsCtx);
+    if (rejectedBodies.size > 0) {
+        memories = memories.filter((memory) => {
+            try {
+                return !rejectedBodies.has(contentHash(fs.readFileSync(memory.filePath, "utf8"), "body"));
+            }
+            catch {
+                return true;
+            }
+        });
+    }
     const judgedUnchanged = poolSize - memories.length;
     // Only what retrieval returned or new material improve never processed (#986).
     const retrievalScope = loadRetrievalScope({ proposalsCtx: opts.proposalsCtx, readOnly }, stashDir);
@@ -758,7 +813,13 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
     recordLedgerAttempt({ proposalsCtx: opts.proposalsCtx }, [...acc.judgedRefs]
         .filter((ref) => !ctx.promotedSourceRefs.has(ref) &&
         !acc.skipReasonByRef.get(ref)?.skips.some((skip) => skip.reason === "promote_create_failed"))
-        .map((ref) => ({ stashDir, ref, source: "consolidate", outcome: "judged_no_action" })));
+        .map((ref) => ({
+        stashDir,
+        ref,
+        source: "consolidate",
+        outcome: "judged_no_action",
+        ...bodyHashOf(ctx.memoryByRef.get(ref)),
+    })));
     return makeConsolidateResult({
         ...summary(),
         promoted: ctx.promoted,
@@ -773,6 +834,17 @@ async function consolidate(opts, config, stashDir, startMs, stateDb) {
         },
     });
 }
+/** The memory's current body hash as a ledger input field; empty when it cannot be read (the row then keeps its 7-day window). */
+function bodyHashOf(memory) {
+    if (!memory)
+        return {};
+    try {
+        return { contentHash: contentHash(fs.readFileSync(memory.filePath, "utf8"), "body") };
+    }
+    catch {
+        return {};
+    }
+}
 /** The conceptId a ref maps to, or undefined for an invalid ref. */
 function conceptIdForRef(ref) {
     try {

package/dist/commands/improve/distill-guards.js

@@ -2,25 +2,24 @@
 // 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/.
 /**
- * Distill guards: related lessons/knowledge shown to the model so it does not
- * overwrite prior generalizations (CLS context), and a cheap check that a
- * proposal does not contradict the memories it came from.
+ * Distill guards: the related lessons, knowledge notes and skills shown to the
+ * writer so it does not repeat or overwrite them (CLS context), and a cheap check
+ * that a proposal does not contradict the memories it came from.
  */
 export const DEFAULT_CLS_ADJACENT_COUNT = 3;
-/** The CLS prompt section (each entry capped at 400 chars); empty when disabled or nothing is related. */
+/** The CLS prompt section (each entry capped at 600 chars); empty when disabled (on unless `enabled: false`) or nothing is related. */
 export function buildClsContext(adjacentItems, config) {
-    if (!config.enabled || adjacentItems.length === 0)
+    if (config.enabled === false || adjacentItems.length === 0)
         return "";
     const lines = [
         "",
-        "## Existing adjacent lessons / knowledge (CLS context)",
-        "The following are semantically related entries already in the stash.",
-        "Your proposal MUST NOT contradict or silently overwrite these — if you",
-        "disagree with one, flag it as contradicted (do not ignore it).",
+        "## Related assets already in the library",
+        "The library already holds these lessons, knowledge notes and skills near this memory. They may be about another subject.",
+        "If one of them already states the rule the memory would give, answer NONE. Do not contradict or overwrite them.",
         "",
     ];
     for (const item of adjacentItems)
-        lines.push(`### ${item.ref}`, item.content.trim().slice(0, 400), "");
+        lines.push(`### ${item.ref}`, item.content.trim().slice(0, 600), "");
     return lines.join("\n");
 }
 /**

package/dist/commands/improve/distill.js

@@ -72,36 +72,46 @@ 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: ["reason", "decision", "description", "when_to_use", "body", "tags"],
     additionalProperties: false,
     properties: {
+        reason: {
+            type: "string",
+            description: "One sentence, written first: the cause and the fix the memory states, or why it states none.",
+        },
+        decision: {
+            type: "string",
+            enum: ["lesson", "none"],
+            description: "`none` when the memory holds no lesson (it records what was done, a design, or steps already written elsewhere): leave the other fields empty. Otherwise `lesson`.",
+        },
         description: {
             type: "string",
-            minLength: 10,
-            description: "Single complete sentence (80-200 chars) summarising what the lesson teaches. No markdown, no leading 'When'/'If'.",
+            description: "Single complete sentence summarising what the lesson teaches. No markdown, no leading 'When'/'If'. Empty for `none`.",
         },
         when_to_use: {
             type: "string",
-            minLength: 10,
-            description: "Single complete sentence describing the concrete trigger condition for the lesson.",
+            description: "Single complete sentence describing the concrete trigger condition for the lesson. Empty for `none`.",
         },
         body: {
             type: "string",
-            minLength: 1,
-            description: "Lesson body — plain markdown, 1-3 short paragraphs of practical guidance.",
+            description: "Lesson body: plain markdown, shorter than the memory, stating only what it and its feedback say. Empty for `none`.",
         },
         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." },
@@ -113,12 +123,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.",
         },
     },
 };
@@ -150,6 +160,19 @@ export function assembleStructuredDistillMarkdown(payload, kind) {
         fm.xrefs = sources;
     return assembleAssetFromString(serializeFrontmatterQuoted(fm), body);
 }
+/**
+ * The writer's answer when it found no lesson: the word NONE, or `decision: "none"` in a reply bound to the schema,
+ * with the reason it gave (`""` for the bare word). `null` for any other reply.
+ */
+function answeredNone(raw) {
+    if (/^[\s"'`*_]*none[\s.!"'`*_]*$/i.test(stripMarkdownFences(raw)))
+        return { reason: "" };
+    const payload = parseEmbeddedJsonResponse(raw);
+    if (payload === null || typeof payload !== "object" || Array.isArray(payload) || payload.decision !== "none") {
+        return null;
+    }
+    return { reason: typeof payload.reason === "string" ? payload.reason.trim() : "" };
+}
 function validateKnowledgeContent(content, inputRef) {
     const findings = [];
     const parsed = parseFrontmatter(content);
@@ -247,7 +270,7 @@ export function buildDistillPrompt(input) {
     }
     lines.push(input.proposalKind === "knowledge"
         ? "Produce the knowledge markdown file now. Start your response with `---` on the first line, followed by a `description:` field whose value is a 1-sentence summary (20–400 chars). Never use placeholder values like `---`, `tbd`, `n/a`, or a single dash. If the source has nothing meaningful to summarize, do NOT produce a proposal — return an empty response instead. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body."
-        : "Produce the lesson markdown file now. Start your response with `---` on the first line, followed by `description:` and `when_to_use:` fields. Both must be real one-sentence summaries (20–400 chars) — never placeholder values like `---`, `tbd`, or `n/a`. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body.");
+        : "Produce the lesson markdown file now. Start your response with `---` on the first line, followed by `description:` and `when_to_use:` fields. Both must be real one-sentence summaries (20–400 chars) — never placeholder values like `---`, `tbd`, or `n/a`. The frontmatter block ends with a second `---` line; do not emit any additional `---` fences in the body. If the memory holds no lesson, answer NONE instead.");
     return lines.join("\n");
 }
 // ── Invocation ───────────────────────────────────────────────────────────────
@@ -339,7 +362,7 @@ export async function akmDistill(options) {
         asset,
         vocabulary: loadRefVocabulary(),
         outcomeWeightEnabled: config.improve?.salience?.outcomeWeightEnabled !== false,
-        similar: options.fetchSimilarLessonsFn ?? fetchTopSimilarLessons,
+        related: options.fetchRelatedFn ?? fetchRelatedAssets,
         lookup,
     };
     const feedbackEvents = readDistillFeedback(run);
@@ -377,6 +400,8 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
             system,
             prompt,
             gate: { config: run.config, enabled: true },
+            // NONE is an answer: a parser that rejected it would ask for a lesson again.
+            parse: (raw) => (answeredNone(raw) ? raw : parseEmbeddedJsonResponse(raw)),
             // The injected test transport never sees the schema.
             request: {
                 ...(run.options.chat === undefined
@@ -409,6 +434,10 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
             ...exclusionMeta(run, true),
         };
     }
+    const none = answeredNone(call.raw);
+    if (none) {
+        return skipDistill(run, outputRef, kind, "nothing_reusable", `The writer found no lesson in ${run.inputRef}${none.reason ? `: ${none.reason}` : "."}`);
+    }
     const assembled = assembleDistilledContent(run, call.raw, kind, outputRef);
     if ("rejection" in assembled)
         return assembled.rejection;
@@ -418,8 +447,20 @@ async function distill(run, targetKind, kind, outputRef, feedbackEvents) {
         content: assembled.content,
         source: run.asset.content,
         descriptionSwapped: assembled.descriptionSwapped,
+        feedback: feedbackLines(feedback),
     });
 }
+/** The feedback that says something, one line each, for the judge. A bare signal says nothing the writer could use. */
+function feedbackLines(feedback) {
+    const lines = [];
+    for (const event of feedback) {
+        const meta = event.metadata ?? {};
+        const detail = (typeof meta.reason === "string" ? meta.reason : "") || (typeof meta.note === "string" ? meta.note : "");
+        if (detail.trim())
+            lines.push(`- [${typeof meta.signal === "string" ? meta.signal : event.eventType}] ${detail.trim()}`);
+    }
+    return lines;
+}
 /** 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);
@@ -485,11 +526,12 @@ async function judgeAndQueue(run, out) {
     let confidence;
     let judged;
     if (qualityGateEnabled(run)) {
-        const similarLessons = await run.similar(content.slice(0, 500), 3);
+        const related = await run.related(content.slice(0, 500), RELATED_COUNT);
         // The judge reads what the generator read: the source body, without its frontmatter (buildDistillPrompt).
         const source = out.source ? parseFrontmatter(out.source).content.trim() : "";
         const verdict = await runLessonQualityJudge(run.config, content, source, run.options.chat, {
-            ...(similarLessons.length > 0 ? { similarLessons } : {}),
+            ...(related.length > 0 ? { related } : {}),
+            ...(out.feedback && out.feedback.length > 0 ? { feedback: out.feedback } : {}),
             ...((run.judgeRunner ?? run.runner) ? { llmRunner: run.judgeRunner ?? run.runner } : {}),
             ...(run.options.signal ? { signal: run.options.signal } : {}),
             onNotices: run.notices.add,
@@ -869,13 +911,13 @@ function readDistillFeedback(run) {
 /** System + user prompt: rejected-proposal context, optional CLS neighbours, stash standards. */
 async function buildDistillMessages(run, feedback, kind, outputRef) {
     const rejectedProposals = rejectedProposalContext(run.stash, run.inputRef, run.options.ctx, run.options.eventsCtx);
-    // CLS interleaving (default off): show related lessons so the model does not overwrite them.
+    // CLS interleaving (default on): show the related lessons, knowledge notes and skills, so the writer neither repeats nor overwrites them.
     const cls = getImproveProcessConfig("distill", run.profile)?.cls ?? {};
     let clsContext = "";
-    if (cls.enabled) {
+    if (cls.enabled !== false) {
         try {
             const query = run.asset.content ? run.asset.content.slice(0, 500) : run.inputRef;
-            clsContext = buildClsContext(await run.similar(query, cls.adjacentCount ?? DEFAULT_CLS_ADJACENT_COUNT), cls);
+            clsContext = buildClsContext(await run.related(query, cls.adjacentCount ?? DEFAULT_CLS_ADJACENT_COUNT), cls);
         }
         catch {
             // CLS context is supplemental.
@@ -904,12 +946,18 @@ async function defaultLookup(ref, stashDir) {
         honorOrigin: false,
     });
 }
-/** Top-N existing lessons similar to `query` (empty when search is unavailable). */
-async function fetchTopSimilarLessons(query, n) {
+/** What the library already holds on a subject: lessons and knowledge notes say it, a skill is how to do it. */
+const RELATED_TYPES = ["lesson", "knowledge", "skill"];
+const RELATED_COUNT = 3;
+/** The top-N lessons, knowledge notes and skills related to `query`, best first (empty when search is unavailable). */
+async function fetchRelatedAssets(query, n) {
     try {
-        const result = await akmSearch({ query, type: "lesson", limit: n, skipLogging: true, eventSource: "improve" });
-        return (result?.hits ?? [])
+        // One search per type: memories outnumber the rest and would fill an untyped list.
+        const results = await Promise.all(RELATED_TYPES.map((type) => akmSearch({ query, type, limit: n, skipLogging: true, eventSource: "improve" })));
+        return results
+            .flatMap((result) => result?.hits ?? [])
             .filter((h) => "path" in h && typeof h.path === "string")
+            .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
             .slice(0, n)
             .map((h) => {
             let content = "";

package/dist/commands/improve/extract-prompt.js

@@ -24,16 +24,21 @@ const EXTRACT_CANDIDATE_NAME_RE = new RegExp(EXTRACT_CANDIDATE_NAME_PATTERN);
  *
  * Shape:
  *   {
- *     "candidates": [{type, name, description, when_to_use?, body, confidence, evidence}, ...],
- *     "rationale_if_empty"?: string
+ *     "candidates": [{type, name, description, when_to_use, body, confidence, evidence}, ...],
+ *     "rationale_if_empty": string
  *   }
  *
  * `additionalProperties: false` at each level so any hallucinated keys are
- * dropped before parsing.
+ * dropped before parsing. Every property is required, as a strict structured-
+ * output provider needs (#1046), and an empty string stands for "none": a
+ * `when_to_use` only a lesson needs, a `rationale_if_empty` only an empty
+ * answer needs. Before, `when_to_use` was optional, so a model that followed
+ * the schema could leave it out of a lesson and the parser dropped the lesson
+ * (#1047).
  */
 export const EXTRACT_JSON_SCHEMA = {
     type: "object",
-    required: ["candidates"],
+    required: ["candidates", "rationale_if_empty"],
     additionalProperties: false,
     properties: {
         candidates: {
@@ -41,7 +46,7 @@ export const EXTRACT_JSON_SCHEMA = {
             description: "Zero or more durable-insight candidates extracted from the session.",
             items: {
                 type: "object",
-                required: ["type", "name", "description", "body", "confidence", "evidence"],
+                required: ["type", "name", "description", "when_to_use", "body", "confidence", "evidence"],
                 additionalProperties: false,
                 properties: {
                     type: {
@@ -62,9 +67,8 @@ export const EXTRACT_JSON_SCHEMA = {
                     },
                     when_to_use: {
                         type: "string",
-                        minLength: 15,
                         maxLength: 400,
-                        description: "Trigger sentence for the candidate; REQUIRED when type=lesson.",
+                        description: "Trigger sentence of at least 15 characters; REQUIRED when type=lesson (a lesson without one is dropped). An empty string for a memory or knowledge candidate.",
                     },
                     body: {
                         type: "string",
@@ -87,8 +91,7 @@ export const EXTRACT_JSON_SCHEMA = {
         },
         rationale_if_empty: {
             type: "string",
-            minLength: 10,
-            description: "Required when `candidates` is empty — explains why nothing rose to durable-insight level.",
+            description: "When `candidates` is empty, one sentence on why nothing rose to durable-insight level; an empty string otherwise.",
         },
     },
 };
@@ -214,10 +217,47 @@ function parseFirstJsonObject(stdout) {
     }
     return { objectFound: true };
 }
+/** The candidate the model wrote when the contract keeps it, else the first rule it breaks. */
+function readCandidate(c) {
+    const { type, name, description, body, confidence, evidence } = c;
+    if (type !== "memory" && type !== "lesson" && type !== "knowledge") {
+        return { problem: "type is not memory, lesson or knowledge" };
+    }
+    if (typeof name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(name)) {
+        return { problem: "name is not a kebab-case slug" };
+    }
+    if (typeof description !== "string" || description.trim().length < 20) {
+        return { problem: "description is shorter than 20 characters" };
+    }
+    if (typeof body !== "string" || body.trim().length < 50)
+        return { problem: "body is shorter than 50 characters" };
+    if (typeof confidence !== "number" || !Number.isFinite(confidence))
+        return { problem: "confidence is not a number" };
+    if (typeof evidence !== "string" || evidence.trim().length < 5) {
+        return { problem: "evidence is shorter than 5 characters" };
+    }
+    // An empty string is how a strict-schema reply says "none".
+    const whenToUse = typeof c.when_to_use === "string" ? c.when_to_use.trim() : "";
+    if (type === "lesson" && whenToUse.length < 15) {
+        return { problem: "a lesson needs a when_to_use of at least 15 characters" };
+    }
+    return {
+        candidate: {
+            type,
+            name,
+            description: description.trim(),
+            ...(whenToUse ? { when_to_use: whenToUse } : {}),
+            body,
+            confidence: Math.max(0, Math.min(1, confidence)),
+            evidence: evidence.trim(),
+        },
+    };
+}
 /**
  * Parse the LLM's JSON response into a structured {@link ExtractPayload}.
  * Defensive — drops candidates that violate the shape rather than failing
- * the whole call. Returns the empty-candidates payload when nothing parses.
+ * the whole call, and names each one in `dropped` so the run can say so.
+ * Returns the empty-candidates payload when nothing parses.
  */
 export function parseExtractPayload(stdout) {
     if (!stdout || stdout.trim().length === 0) {
@@ -238,42 +278,24 @@ export function parseExtractPayload(stdout) {
     }
     const rawCandidates = obj.candidates;
     const candidates = [];
+    const dropped = [];
     for (const raw of rawCandidates) {
-        if (!raw || typeof raw !== "object")
+        if (!raw || typeof raw !== "object") {
+            dropped.push("candidate dropped: not an object");
             continue;
+        }
         const c = raw;
-        const type = c.type;
-        if (type !== "memory" && type !== "lesson" && type !== "knowledge")
-            continue;
-        if (typeof c.name !== "string" || !EXTRACT_CANDIDATE_NAME_RE.test(c.name))
-            continue;
-        if (typeof c.description !== "string" || c.description.trim().length < 20)
-            continue;
-        if (typeof c.body !== "string" || c.body.trim().length < 50)
+        const read = readCandidate(c);
+        if ("problem" in read) {
+            dropped.push(`${typeof c.type === "string" ? c.type : "candidate"}:${typeof c.name === "string" ? c.name : "(unnamed)"} dropped: ${read.problem}`);
             continue;
-        if (typeof c.confidence !== "number" || !Number.isFinite(c.confidence))
-            continue;
-        if (typeof c.evidence !== "string" || c.evidence.trim().length < 5)
-            continue;
-        if (type === "lesson") {
-            if (typeof c.when_to_use !== "string" || c.when_to_use.trim().length < 15)
-                continue;
         }
-        const confidence = Math.max(0, Math.min(1, c.confidence));
-        const candidate = {
-            type,
-            name: c.name,
-            description: c.description.trim(),
-            body: c.body,
-            confidence,
-            evidence: c.evidence.trim(),
-        };
-        if (typeof c.when_to_use === "string")
-            candidate.when_to_use = c.when_to_use.trim();
-        candidates.push(candidate);
+        candidates.push(read.candidate);
     }
     const result = { candidates };
-    if (typeof obj.rationale_if_empty === "string") {
+    if (dropped.length > 0)
+        result.dropped = dropped;
+    if (typeof obj.rationale_if_empty === "string" && obj.rationale_if_empty.trim()) {
         result.rationale_if_empty = obj.rationale_if_empty.trim();
     }
     return result;

package/dist/commands/improve/extract.js

@@ -468,7 +468,8 @@ async function processSession(run, sessionRef, gate) {
         });
     }
     const { payload } = extraction;
-    const warnings = [];
+    // A candidate the contract refused is reported, not silently lost (#1047).
+    const warnings = [...(payload.dropped ?? [])];
     // Provenance xrefs are added only after the cited session asset exists.
     const { warning, ...sessionAsset } = await maybeWriteSessionAsset(run, data);
     if (warning)

package/dist/commands/improve/preparation.js

@@ -601,6 +601,16 @@ export function buildSnapshotManifest(args) {
     const latestNegativeTs = new Map();
     const feedback = new Map(candidates.map((r) => [r.ref, { hasSignal: false, positive: 0, negative: 0 }]));
     if (candidates.length > 0) {
+        // When each ref's accepted feedback proposals were created: a fix event is acted on once one exists at or after it.
+        const fixedAt = new Map();
+        if (stashDir) {
+            withRunState(eventsCtx, args.readOnly !== true, (db) => {
+                for (const p of listStateProposals(db, { stashDir, status: "accepted" })) {
+                    if (p.source === "feedback")
+                        fixedAt.set(p.ref, [...(fixedAt.get(p.ref) ?? []), p.createdAt]);
+                }
+            });
+        }
         for (const e of readEvents({ type: "feedback" }, eventsCtx).events) {
             const ref = e.ref ? refByKey.get(e.ref) : undefined;
             const entry = ref ? feedback.get(ref) : undefined;
@@ -612,8 +622,11 @@ export function buildSnapshotManifest(args) {
                 entry.hasSignal = true;
                 if (ts > (latestFeedbackTs.get(ref) ?? ""))
                     latestFeedbackTs.set(ref, ts);
-                if (signal === "negative" && ts > (latestNegativeTs.get(ref) ?? ""))
+                const fixApplied = e.metadata?.fix !== undefined &&
+                    (fixedAt.get(e.ref ?? "") ?? []).some((createdAt) => createdAt >= ts);
+                if (signal === "negative" && !fixApplied && ts > (latestNegativeTs.get(ref) ?? "")) {
                     latestNegativeTs.set(ref, ts);
+                }
             }
             if (signal === "positive")
                 entry.positive++;

package/dist/commands/improve/reflect.js

@@ -13,11 +13,13 @@
  * pre-dispatch refusals still emit both).
  */
 import fs from "node:fs";
+import path from "node:path";
+import { assetPathForName, stashDirFor } from "../../core/asset/asset-placement.js";
 import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
-import { resolveStashDir } from "../../core/common.js";
+import { isWithin, resolveStashDir, safeRealpath } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
 import { generatedContentRejection } from "../../core/content-safety.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
@@ -248,7 +250,7 @@ export const REFLECT_JSON_SCHEMA = {
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
-const REFLECT_UNSCOPED_JSON_SCHEMA = {
+export const REFLECT_UNSCOPED_JSON_SCHEMA = {
     type: "object",
     required: ["ref", "confidence", "frontmatterPatch"],
     additionalProperties: false,
@@ -539,6 +541,24 @@ function unsupportedTypeFailure(ref, type, detail, emitFailed) {
         },
     };
 }
+/**
+ * A proposal writes the file derived from the ref's type and name under the bundle's root. An asset indexed
+ * anywhere else (a skill's `references/a.md` is `knowledge/skills/<name>/references/a`) has nothing there, so the
+ * proposal would be a `create` and accepting it would add a second file for the ref (#1052).
+ */
+function fileOutsideLayoutFailure(ref, file, writes, emitFailed) {
+    emitFailed("unsupported_type", "file_outside_layout", ref);
+    return {
+        failure: {
+            schemaVersion: 2,
+            ok: false,
+            reason: "unsupported_type",
+            error: `Reflect refused: the file for ${ref} is ${file}, but a proposal would write ${writes}. Edit the file directly.`,
+            ref,
+            exitCode: null,
+        },
+    };
+}
 /** The target's parsed ref and current content, or a refusal for a type reflect cannot patch. */
 async function resolveReflectSource(options, stash, emitFailed) {
     if (!options.ref)
@@ -549,18 +569,21 @@ async function resolveReflectSource(options, stash, emitFailed) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "secret material is never read or sent to an LLM", emitFailed);
     }
     let assetContent = options.assetContent;
+    let assetFile;
     if (assetContent === undefined) {
         try {
             const qualifiedRef = options.itemRef ?? options.ref;
             const localFilePath = await findAssetFilePath(qualifiedRef, stash);
             if (localFilePath && fs.existsSync(localFilePath)) {
-                assetContent = fs.readFileSync(localFilePath, "utf8");
+                assetFile = localFilePath;
             }
             else {
                 const entry = await lookup(parseRefInput(qualifiedRef));
                 if (entry?.filePath && fs.existsSync(entry.filePath))
-                    assetContent = fs.readFileSync(entry.filePath, "utf8");
+                    assetFile = entry.filePath;
             }
+            if (assetFile !== undefined)
+                assetContent = fs.readFileSync(assetFile, "utf8");
         }
         catch {
             // An index miss is not fatal: reflect then has no content to patch.
@@ -570,6 +593,15 @@ async function resolveReflectSource(options, stash, emitFailed) {
         (assetContent === undefined || parseFrontmatter(assetContent).frontmatter === null)) {
         return unsupportedTypeFailure(options.ref, parsedRef.type, "its content is not frontmatter + markdown", emitFailed);
     }
+    // A file in another bundle is `createProposal`'s to refuse (#1000); this one is in the proposal's own bundle.
+    const root = path.resolve(options.target?.root ?? stash);
+    const typeDir = stashDirFor(parsedRef.type);
+    if (assetFile !== undefined && typeDir !== undefined && isWithin(assetFile, root)) {
+        const writes = assetPathForName(parsedRef.type, path.join(root, typeDir), parsedRef.name);
+        if (safeRealpath(writes) !== safeRealpath(assetFile)) {
+            return fileOutsideLayoutFailure(options.ref, assetFile, writes, emitFailed);
+        }
+    }
     return { assetContent, parsedRef };
 }
 /**