akm-cli 0.9.25-alpha.1 → 0.9.25-alpha.3

package/dist/commands/improve/reflect.js

@@ -2,23 +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/.
 /**
- * `akm reflect [ref]` — ask an engine for a revised asset and queue it as a
- * proposal (`source: "reflect"`). Reflect never writes an asset: the proposal
- * queue is the only path, `akm proposal accept` the bridge.
+ * `akm reflect [ref]` — ask an engine whether an asset's `description`,
+ * `when_to_use` and title need a fix, and queue the asset with that fix as a
+ * proposal (`source: "reflect"`). The engine never writes the body: akm keeps
+ * it byte for byte. Reflect never writes an asset: the proposal queue is the
+ * only path, `akm proposal accept` the bridge.
  *
  * Every invocation closes with one `reflect_completed` event; `reflect_invoked`
  * is emitted once the dispatch has validated its credentials (deterministic
  * pre-dispatch refusals still emit both).
  */
 import fs from "node:fs";
-import path from "node:path";
-import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
+import { serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.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 { loadConfig } from "../../core/config/config.js";
-import { generatedContentRejection, stripReflectPromptScaffolding } from "../../core/content-safety.js";
+import { generatedContentRejection } from "../../core/content-safety.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
@@ -26,23 +27,21 @@ import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
 import { warn, warnOnce } from "../../core/warn.js";
-import { MODEL_WORK_TOOLS } from "../../execution/source.js";
 import { lookup } from "../../indexer/indexer.js";
-import { DEFAULT_MODEL_WORK_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { buildExecution, resolveExecution } from "../../integrations/agent/execution.js";
-import { buildReflectOutputRepairPrompt, buildReflectPrompt, parseAgentProposalPayload, REFLECT_CONTENT_CAP, REFLECT_TRUNCATION_MARKER, } from "../../integrations/agent/prompts.js";
+import { buildReflectOutputRepairPrompt, buildReflectPrompt, REFLECT_CONTENT_CAP, } from "../../integrations/agent/prompts.js";
 import { runnerIsLlm } from "../../integrations/agent/runner.js";
 import { assertRunnerCredentials, collectDispatchSensitiveValues, } from "../../integrations/agent/runner-dispatch.js";
 import { isJsonSchemaKnownUnsupported, LlmCallError } from "../../llm/client.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
-import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
+import { isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
 import { CHARS_PER_TOKEN, DEFAULT_CONTEXT_LENGTH_TOKENS } from "./consolidate/chunking.js";
-import { deriveLessonRef } from "./distill.js";
 import { findAssetFilePath } from "./eligibility.js";
 import { resolveImproveExecution } from "./execution.js";
 import { recordLedgerAttempt } from "./ledger.js";
-import { classifyReflectChange, splitFrontmatter } from "./reflect-noise.js";
+import { classifyReflectChange, findReflectDefect, splitFrontmatter } from "./reflect-noise.js";
 import { loadRetrievalQueries, runRetrievalRegressionGate } from "./retrieval-gate.js";
 import { callStageOnce, errMessage, mintProposal, noticeSet, rejectedProposalContext, resolveQualityGateJudge, runReflectQualityJudge, } from "./stage.js";
 const MAX_FEEDBACK_LINES = 10;
@@ -67,7 +66,7 @@ function readRecentFeedback(ref, eventsCtx) {
     }
 }
 /**
- * Types reflect may rewrite: its output is frontmatter + markdown, which would
+ * Types reflect may patch: its output is frontmatter + markdown, which would
  * break a script or env file. Another type is allowed only when its current
  * content already has that shape; secrets are never read.
  */
@@ -81,99 +80,12 @@ export const REFLECT_ALLOWED_TYPES = new Set([
     "workflow",
 ]);
 const REFLECT_REFUSED_TYPES = new Set(["secret"]);
-/** Identity fields the model may never change (a renamed `name` breaks ref resolution). */
-const PROTECTED_FRONTMATTER_FIELDS = new Set(["name", "ref", "id", "slug", "type"]);
 /** Lesson lint findings for the prompt: a concrete starting point for the revision. */
 function buildSchemaHints(type, content) {
     if (!content || type !== "lesson")
         return [];
     return lintLessonContent(content, "reflect").findings.map((f) => `[${f.kind}] ${f.message}`);
 }
-/**
- * Lessons related to a skill: its derived lesson, lessons distilled from it,
- * and lessons citing it in `sources`. Without independent feedback on the skill,
- * lessons reflect itself produced are dropped so its own output is not fed
- * back as evidence.
- */
-async function readRelatedLessons(stash, ref, parsedRef, itemRef, eventsCtx) {
-    if (parsedRef.type !== "skill")
-        return [];
-    const cache = new Map();
-    const read = (filePath) => {
-        const key = path.resolve(filePath);
-        const cached = cache.get(key) ?? fs.readFileSync(filePath, "utf8");
-        cache.set(key, cached);
-        return cached;
-    };
-    const related = new Map();
-    const derivedLessonRef = deriveLessonRef(ref);
-    const candidateRefs = new Set([derivedLessonRef]);
-    const derivedLessonPath = path.join(stash, "lessons", `${parseRefInput(derivedLessonRef).name}.md`);
-    if (fs.existsSync(derivedLessonPath)) {
-        related.set(derivedLessonRef, { ref: derivedLessonRef, content: read(derivedLessonPath) });
-    }
-    try {
-        const keys = new Set([itemRef ?? ref]);
-        for (const event of readEvents({ type: "distill_invoked" }, readOnlyEventsContext(eventsCtx)).events) {
-            if (event.ref === undefined || !keys.has(event.ref))
-                continue;
-            const proposalRef = typeof event.metadata?.proposalRef === "string" ? event.metadata.proposalRef : undefined;
-            if (proposalRef && lenientRefType(proposalRef) === "lesson")
-                candidateRefs.add(proposalRef);
-        }
-    }
-    catch {
-        // best-effort
-    }
-    for (const candidateRef of candidateRefs) {
-        try {
-            const filePath = await findAssetFilePath(candidateRef, stash);
-            if (filePath && fs.existsSync(filePath))
-                related.set(candidateRef, { ref: candidateRef, content: read(filePath) });
-        }
-        catch {
-            // An index miss is not fatal.
-        }
-    }
-    try {
-        const lessonsDir = path.join(stash, "lessons");
-        if (fs.existsSync(lessonsDir)) {
-            for (const fileName of fs.readdirSync(lessonsDir)) {
-                if (!fileName.endsWith(".md"))
-                    continue;
-                const content = read(path.join(lessonsDir, fileName));
-                const sources = parseFrontmatter(content).data.sources;
-                if (!Array.isArray(sources) || !sources.some((s) => typeof s === "string" && s.trim() === ref))
-                    continue;
-                const lessonRef = conceptIdFromTypeName("lesson", fileName.slice(0, -3));
-                if (!related.has(lessonRef))
-                    related.set(lessonRef, { ref: lessonRef, content });
-            }
-        }
-    }
-    catch {
-        // best-effort
-    }
-    let hasIndependentFeedback = true;
-    try {
-        hasIndependentFeedback = readEvents({ type: "feedback", ref }, readOnlyEventsContext(eventsCtx)).events.length > 0;
-    }
-    catch {
-        // Unknown: keep every lesson.
-    }
-    if (!hasIndependentFeedback) {
-        for (const [lessonRef, lesson] of related) {
-            try {
-                if (parseFrontmatter(lesson.content).data.derived_from_reflect === true)
-                    related.delete(lessonRef);
-            }
-            catch {
-                // Unparseable frontmatter: keep it.
-            }
-        }
-    }
-    return [...related.values()];
-}
 /** The asset type of a maybe-ref, or `""` when it does not parse. */
 function lenientRefType(ref) {
     if (!ref)
@@ -185,35 +97,21 @@ function lenientRefType(ref) {
         return "";
     }
 }
-/**
- * Cut a duplicate frontmatter block the model appended after its rewrite.
- * Requires a balanced fence AND `key:` lines so thematic breaks survive.
- */
-function stripAppendedFrontmatter(body) {
-    const match = body.match(/\n---\r?\n([\s\S]*?)\n---\r?\n/);
-    if (!match || !/^\w[\w-]*:/m.test(match[1]))
-        return body;
-    return body.slice(0, body.indexOf(match[0])).replace(/\s+$/, "");
-}
 /**
  * A description derived from existing metadata (title, first heading, first
  * prose sentence) that passes `isValidDescription`, or `undefined`. Never
  * free-form invention.
  */
-function deriveDescriptionFromAsset(title, proposedBody, sourceBody, targetRef) {
+function deriveDescriptionFromAsset(title, body, targetRef) {
     const candidates = [];
     if (typeof title === "string" && title.trim())
         candidates.push({ text: title.trim(), kind: "fragment" });
-    for (const body of [proposedBody, sourceBody]) {
-        const heading = body.match(/^#{1,6}\s+(.+?)\s*$/m)?.[1];
-        if (heading)
-            candidates.push({ text: heading.trim(), kind: "fragment" });
-    }
-    for (const body of [proposedBody, sourceBody]) {
-        const sentence = firstProseSentence(body);
-        if (sentence)
-            candidates.push({ text: sentence, kind: "prose" });
-    }
+    const heading = body.match(/^#{1,6}\s+(.+?)\s*$/m)?.[1];
+    if (heading)
+        candidates.push({ text: heading.trim(), kind: "fragment" });
+    const sentence = firstProseSentence(body);
+    if (sentence)
+        candidates.push({ text: sentence, kind: "prose" });
     for (const { text, kind } of candidates) {
         const normalized = text
             .replace(/`/g, "")
@@ -242,81 +140,71 @@ function firstProseSentence(body) {
     return "";
 }
 /**
- * Reflect's content rails: the source frontmatter is restored and the model's
- * frontmatter merged on top except identity fields; a stray or appended
- * frontmatter block and echoed run-only guidance are stripped; a missing
- * required description is derived deterministically; a body outside the size
- * ratios or echoing the truncation notice is flagged for review.
+ * The asset with the patch applied, or `undefined` when the patch changes
+ * nothing (or there is no asset to patch). The body is the source's own, byte
+ * for byte; the one thing akm adds to it is a `# title` heading it lacks. A
+ * required description that neither the source nor the patch has is derived
+ * from the asset's own text (#636). Only the changed keys' frontmatter lines are
+ * rewritten: every other line is kept as it is, so a source whose YAML the
+ * parser reads only in part (a broken description beside a list) loses nothing.
  */
-export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
-    const warnings = [];
-    const { fmText: sourceFmText, body: sourceBody } = sourceContent
-        ? splitFrontmatter(sourceContent)
-        : { fmText: null, body: "" };
-    const sourceFm = sourceFmText !== null ? parseFrontmatter(sourceContent ?? "").data : {};
-    const { fmText: llmFmText, body: rawLlmBody } = splitFrontmatter(payload.content);
-    let llmFm = {};
-    if (llmFmText !== null) {
-        warnings.push("LLM emitted frontmatter in content; stripped and merged through identity guard.");
-        try {
-            llmFm = parseFrontmatter(payload.content).data;
-        }
-        catch {
-            llmFm = {};
-        }
-    }
-    if (payload.frontmatter && typeof payload.frontmatter === "object")
-        llmFm = { ...llmFm, ...payload.frontmatter };
-    for (const field of PROTECTED_FRONTMATTER_FIELDS) {
-        if (field in llmFm && llmFm[field] !== sourceFm[field]) {
-            warnings.push(`LLM attempted to change protected frontmatter field "${field}"; restored from source.`);
-            delete llmFm[field];
-        }
-    }
-    const mergedFm = { ...sourceFm, ...llmFm };
-    for (const field of PROTECTED_FRONTMATTER_FIELDS)
-        if (field in sourceFm)
-            mergedFm[field] = sourceFm[field];
-    const scaffolding = stripReflectPromptScaffolding(stripAppendedFrontmatter(rawLlmBody.replace(/^\s+/, "")));
-    const cleanedBody = scaffolding.content;
-    if (scaffolding.stripped) {
-        warnings.push('Removed echoed run-only "Avoid These Patterns" guidance from the proposed asset body (#963).');
-    }
+export function applyReflectPatch(patch, sourceContent, targetRef) {
+    if (!sourceContent.trim())
+        return undefined;
+    const { fmText, body: sourceBody } = splitFrontmatter(sourceContent);
+    // A fence that is opened and never closed (`---` fused onto the last value)
+    // would leave the old block in the body under a new one: a person fixes it.
+    if (fmText === null && /^---\r?\n/.test(sourceContent))
+        return undefined;
+    const sourceFm = fmText !== null ? parseFrontmatter(sourceContent).data : {};
+    const { title, ...changes } = patch;
+    const addTitle = title !== undefined && !/^#[ \t]+\S/m.test(sourceBody);
+    const body = addTitle ? `# ${title}\n\n${sourceBody.replace(/^(\r?\n)+/, "")}` : sourceBody;
     // Only a source that already has frontmatter but no description gets one:
     // injecting a whole block, or overwriting an authored one, is out of scope.
     const refType = lenientRefType(targetRef);
-    const desc = mergedFm.description;
-    const sourceHadFrontmatter = sourceFmText !== null && Object.keys(sourceFm).length > 0;
+    const desc = changes.description ?? sourceFm.description;
     if (refType &&
         requiresDescription(refType) &&
         (typeof desc !== "string" || desc.trim().length === 0) &&
-        sourceHadFrontmatter) {
-        const derived = deriveDescriptionFromAsset(mergedFm.title, cleanedBody, sourceBody, targetRef);
-        if (derived) {
-            mergedFm.description = derived;
-            warnings.push("Synthesized a deterministic `description` from title/heading (#636) — source and proposal lacked one.");
+        Object.keys(sourceFm).length > 0) {
+        const derived = deriveDescriptionFromAsset(sourceFm.title, body, targetRef);
+        if (derived)
+            changes.description = derived;
+    }
+    for (const key of Object.keys(changes))
+        if (changes[key] === sourceFm[key])
+            delete changes[key];
+    if (!addTitle && Object.keys(changes).length === 0)
+        return undefined;
+    // No frontmatter at all stays body-only unless the patch adds a field. The
+    // blank line after a closing fence is part of the source body, so only a
+    // block or heading akm adds brings its own.
+    if (fmText === null) {
+        if (Object.keys(changes).length === 0)
+            return { content: body };
+        const content = `---\n${serializeFrontmatter(changes)}\n---\n\n${body}`;
+        return { content, frontmatter: parseFrontmatter(content).data };
+    }
+    const content = `---\n${patchFrontmatterLines(fmText, changes)}\n---\n${addTitle ? "\n" : ""}${body}`;
+    return { content, frontmatter: parseFrontmatter(content).data };
+}
+/** The frontmatter text with each changed key's lines (the key line and its indented continuation) replaced, or appended. */
+function patchFrontmatterLines(fmText, changes) {
+    const lines = fmText.split(/\r?\n/);
+    for (const [key, value] of Object.entries(changes)) {
+        const replacement = serializeFrontmatter({ [key]: value }).split("\n");
+        const start = lines.findIndex((line) => line.startsWith(`${key}:`));
+        if (start === -1) {
+            lines.push(...replacement);
+            continue;
         }
+        let end = start + 1;
+        while (end < lines.length && /^[ \t]/.test(lines[end] ?? ""))
+            end++;
+        lines.splice(start, end - start, ...replacement);
     }
-    const size = checkReflectSize(sourceBody, cleanedBody);
-    let sizeGuardRatio;
-    if (!size.ok) {
-        const shrink = size.code === "EXCESSIVE_SHRINKAGE";
-        warnings.push(`${size.code} — proposed body is ${(size.ratio * 100).toFixed(0)}% of source (${shrink ? "minimum 50%" : "maximum 250%"}) for ref ${targetRef}. ${shrink ? "Concrete content was likely deleted." : "Speculative material was likely added."} Flagged for review.`);
-        sizeGuardRatio = { code: size.code, ratio: size.ratio };
-    }
-    const truncationMarkerLeaked = cleanedBody.includes(REFLECT_TRUNCATION_MARKER);
-    if (truncationMarkerLeaked) {
-        warnings.push(`Proposed body for ref ${targetRef} contains the truncation-notice text the model was shown for a capped source asset ("${REFLECT_TRUNCATION_MARKER}"). The model likely echoed the notice instead of writing real content. Flagged for review.`);
-    }
-    // No frontmatter at all stays body-only, never gaining a stray `---`.
-    const hasFrontmatter = Object.keys(mergedFm).length > 0;
-    return {
-        content: hasFrontmatter ? assembleAssetFromString(serializeFrontmatter(mergedFm), cleanedBody) : cleanedBody,
-        ...(hasFrontmatter ? { frontmatter: mergedFm } : {}),
-        warnings,
-        ...(sizeGuardRatio ? { sizeGuardRatio } : {}),
-        ...(truncationMarkerLeaked ? { truncationMarkerLeaked } : {}),
-    };
+    return lines.join("\n");
 }
 // ── Output contract ──────────────────────────────────────────────────────────
 //
@@ -326,11 +214,12 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
 // repaired once, whatever engine produced it.
 const REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA = {
     type: "object",
-    required: ["description", "when_to_use"],
+    required: ["description", "when_to_use", "title"],
     additionalProperties: false,
     properties: {
         description: { type: ["string", "null"] },
         when_to_use: { type: ["string", "null"] },
+        title: { type: ["string", "null"] },
     },
 };
 const REFLECT_CONFIDENCE_SCHEMA = {
@@ -341,21 +230,19 @@ const REFLECT_CONFIDENCE_SCHEMA = {
 };
 export const REFLECT_JSON_SCHEMA = {
     type: "object",
-    required: ["content", "confidence", "frontmatterPatch"],
+    required: ["confidence", "frontmatterPatch"],
     additionalProperties: false,
     properties: {
-        content: { type: "string", description: "Complete improved markdown body without YAML frontmatter." },
         confidence: REFLECT_CONFIDENCE_SCHEMA,
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
 const REFLECT_UNSCOPED_JSON_SCHEMA = {
     type: "object",
-    required: ["ref", "content", "confidence", "frontmatterPatch"],
+    required: ["ref", "confidence", "frontmatterPatch"],
     additionalProperties: false,
     properties: {
         ref: { type: "string", description: "Selected asset ref as a subdir-qualified conceptId." },
-        content: { type: "string", description: "Complete improved markdown body without YAML frontmatter." },
         confidence: { type: "number", minimum: 0, maximum: 1, description: "Self-reported quality confidence in [0, 1]." },
         frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
@@ -388,67 +275,48 @@ function parseReflectConfidence(value) {
     }
     return value;
 }
+const REFLECT_PATCH_FIELDS = ["description", "when_to_use", "title"];
 function parseReflectFrontmatterPatch(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         throw new Error('direct reflect response missing required object field "frontmatterPatch"');
     }
-    const patch = value;
-    const keys = Object.keys(patch).sort();
-    if (keys.length !== 2 || keys[0] !== "description" || keys[1] !== "when_to_use") {
-        throw new Error("direct reflect frontmatterPatch fields must be exactly: description, when_to_use");
+    const fields = value;
+    if (Object.keys(fields).length !== REFLECT_PATCH_FIELDS.length || REFLECT_PATCH_FIELDS.some((f) => !(f in fields))) {
+        throw new Error(`direct reflect frontmatterPatch fields must be exactly: ${REFLECT_PATCH_FIELDS.join(", ")}`);
     }
-    const frontmatter = {};
-    for (const field of ["description", "when_to_use"]) {
-        const fieldValue = patch[field];
+    const patch = {};
+    for (const field of REFLECT_PATCH_FIELDS) {
+        const fieldValue = fields[field];
         if (fieldValue === null)
             continue;
         if (typeof fieldValue !== "string" || !fieldValue.trim() || /[\r\n]/.test(fieldValue)) {
             throw new Error(`direct reflect frontmatterPatch.${field} must be a non-empty single-line string or null`);
         }
-        frontmatter[field] = fieldValue.trim();
+        patch[field] = fieldValue.trim();
     }
-    return Object.keys(frontmatter).length > 0 ? frontmatter : undefined;
+    return patch;
 }
 function parseSchemaReflectOutput(raw, targetRef) {
     const parsed = parseEmbeddedJsonResponse(raw);
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
         throw new Error("direct reflect response was not valid JSON");
     }
-    const expectedKeys = targetRef
-        ? ["confidence", "content", "frontmatterPatch"]
-        : ["confidence", "content", "frontmatterPatch", "ref"];
+    const expectedKeys = targetRef ? ["confidence", "frontmatterPatch"] : ["confidence", "frontmatterPatch", "ref"];
     const actualKeys = Object.keys(parsed).sort();
     if (actualKeys.length !== expectedKeys.length || actualKeys.some((key, index) => key !== expectedKeys[index])) {
         throw new Error(`direct reflect response fields must be exactly: ${expectedKeys.join(", ")}`);
     }
-    if (typeof parsed.content !== "string" || !parsed.content.trim()) {
-        throw new Error('direct reflect response missing required string field "content"');
-    }
     const ref = targetRef ?? (typeof parsed.ref === "string" ? parsed.ref.trim() : "");
     if (!ref)
         throw new Error('direct reflect response missing required string field "ref"');
-    const frontmatter = parseReflectFrontmatterPatch(parsed.frontmatterPatch);
     return {
         ref,
-        content: parsed.content,
         confidence: parseReflectConfidence(parsed.confidence),
-        ...(frontmatter ? { frontmatter } : {}),
+        patch: parseReflectFrontmatterPatch(parsed.frontmatterPatch),
     };
 }
 function parseFramedReflectOutput(raw, targetRef) {
-    const normalized = raw.replaceAll("\r\n", "\n").trim();
-    const beginMarker = "AKM_REFLECT_CONTENT_BEGIN\n";
-    const endMarker = "\nAKM_REFLECT_CONTENT_END";
-    const beginIndex = normalized.indexOf(beginMarker);
-    if (beginIndex < 0 || (beginIndex > 0 && normalized[beginIndex - 1] !== "\n")) {
-        throw new Error("direct reflect response missing AKM_REFLECT_CONTENT_BEGIN marker");
-    }
-    const contentStart = beginIndex + beginMarker.length;
-    const endIndex = normalized.lastIndexOf(endMarker);
-    if (endIndex < contentStart || normalized.slice(endIndex + endMarker.length).trim()) {
-        throw new Error("direct reflect response missing terminal AKM_REFLECT_CONTENT_END marker");
-    }
-    const headerLines = normalized.slice(0, beginIndex).trim().split("\n").filter(Boolean);
+    const headerLines = raw.replaceAll("\r\n", "\n").trim().split("\n").filter(Boolean);
     const header = (prefix) => headerLines.find((line) => line.startsWith(prefix));
     const confidenceLine = header("AKM_REFLECT_CONFIDENCE:");
     const refLine = header("AKM_REFLECT_REF:");
@@ -464,9 +332,6 @@ function parseFramedReflectOutput(raw, targetRef) {
     const ref = targetRef ?? refLine?.slice("AKM_REFLECT_REF:".length).trim() ?? "";
     if (!ref)
         throw new Error("direct reflect response contained an empty AKM_REFLECT_REF value");
-    const content = normalized.slice(contentStart, endIndex);
-    if (!content.trim())
-        throw new Error("direct reflect response contained empty framed content");
     let parsedPatch;
     try {
         parsedPatch = JSON.parse(patchLine.slice("AKM_REFLECT_FRONTMATTER_PATCH:".length).trim());
@@ -474,9 +339,11 @@ function parseFramedReflectOutput(raw, targetRef) {
     catch {
         throw new Error("direct reflect response contained invalid frontmatter patch JSON");
     }
-    const frontmatter = parseReflectFrontmatterPatch(parsedPatch);
-    const confidence = parseReflectConfidence(Number(confidenceText));
-    return { ref, content, confidence, ...(frontmatter ? { frontmatter } : {}) };
+    return {
+        ref,
+        confidence: parseReflectConfidence(Number(confidenceText)),
+        patch: parseReflectFrontmatterPatch(parsedPatch),
+    };
 }
 /**
  * One reflect iteration on any engine, as an agent-shaped result (errors
@@ -494,7 +361,7 @@ export async function runReflectIteration(opts) {
         ? (opts.timeoutMs ?? null)
         : Object.hasOwn(opts.runner, "timeoutMs")
             ? (opts.runner.timeoutMs ?? null)
-            : DEFAULT_MODEL_WORK_TIMEOUT_MS;
+            : DEFAULT_LLM_TIMEOUT_MS;
     const deadline = typeof configuredTimeout === "number" ? start + configuredTimeout : undefined;
     const messages = [{ role: "user", content: opts.prompt ?? "" }];
     if (opts.priorDraft !== undefined && opts.iteration > 0) {
@@ -516,16 +383,8 @@ export async function runReflectIteration(opts) {
             parsed: { outputMode: opts.outputMode, repairAttempts },
         };
     };
-    // A reply that broke the contract. An agent or SDK engine's failure names the engine; an LLM
-    // reply keeps its message, because improve feeds a failed reflect's `error` into the next
-    // prompts as a pattern to avoid, and rewording it would change those requests.
-    const invalidReply = (err, reply) => {
-        if (runnerIsLlm(opts.runner))
-            return failure(err, "parse_error", reply, 0);
-        const attempts = repairAttempts + 1;
-        const message = `Engine "${opts.runner.engine}" reply was not a valid reflect proposal after ${attempts} attempt${attempts === 1 ? "" : "s"}: ${errMessage(err)}`;
-        return failure(new Error(message), "parse_error", reply, 0);
-    };
+    // A reply that broke the contract; its message is the parser's, on every engine kind.
+    const invalidReply = (err, reply) => failure(err, "parse_error", reply, 0);
     // The result of the dispatch that failed, kept for an agent or SDK engine.
     let dispatched;
     // Reflect parses and repairs its own reply (the repair turn below), so one dispatch, unvalidated.
@@ -669,7 +528,7 @@ function unsupportedTypeFailure(ref, type, detail, emitFailed) {
         },
     };
 }
-/** The target's parsed ref and current content, or a refusal for a type reflect cannot rewrite. */
+/** 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)
         return { assetContent: undefined, parsedRef: undefined };
@@ -693,7 +552,7 @@ async function resolveReflectSource(options, stash, emitFailed) {
             }
         }
         catch {
-            // An index miss is not fatal: the agent can still propose a fresh asset.
+            // An index miss is not fatal: reflect then has no content to patch.
         }
     }
     if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type) &&
@@ -756,7 +615,7 @@ function preflightReflectDispatch(runnerSpec, onNotices) {
     const prepared = resolveExecution({
         content: "Validate reflect operation transport before dispatch.",
         runner: runnerSpec,
-        current: { tools: MODEL_WORK_TOOLS },
+        modelWork: true,
     });
     const lowered = buildExecution(prepared.request, prepared.runner);
     onNotices(lowered.notices);
@@ -765,7 +624,7 @@ function preflightReflectDispatch(runnerSpec, onNotices) {
 /**
  * The flat 12k content cap exists for CLI argv; the HTTP runner can spend half
  * its context window (after the rest of the prompt) on the asset, reserving
- * the other half for the rewrite. Never below the flat floor.
+ * the other half for the reply. Never below the flat floor.
  */
 function computeReflectContentBudgetChars(promptInput, runnerSpec) {
     if (!runnerIsLlm(runnerSpec) || !promptInput.assetContent?.trim())
@@ -775,13 +634,10 @@ function computeReflectContentBudgetChars(promptInput, runnerSpec) {
     return Math.max(REFLECT_CONTENT_CAP, Math.floor((window - overhead) / 2));
 }
 /** Every read-only prompt input, shared by dispatch and `--show-prompt`. */
-async function gatherReflectPromptSources(options, stash, parsedRef, assetContent) {
+function gatherReflectPromptSources(options, stash, parsedRef, assetContent) {
     return {
         feedback: readRecentFeedback(options.ref ? (options.itemRef ?? options.ref) : undefined, options.eventsCtx),
         schemaHints: buildSchemaHints(parsedRef?.type ?? "", assetContent),
-        relatedLessons: options.ref && parsedRef
-            ? await readRelatedLessons(stash, options.ref, parsedRef, options.itemRef, options.eventsCtx)
-            : [],
         rejectedProposals: rejectedProposalContext(stash, options.ref, options.ctx, options.eventsCtx),
         standardsContext: resolveStandardsContext(options.ref, stash),
     };
@@ -789,7 +645,7 @@ async function gatherReflectPromptSources(options, stash, parsedRef, assetConten
 /** The exact prompt reflect sends, shared by dispatch and `--show-prompt`. */
 function buildReflectPromptText(args) {
     const { options, parsedRef, assetContent, sources, runnerSpec, priorDraft } = args;
-    const { feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext } = sources;
+    const { feedback, schemaHints, rejectedProposals, standardsContext } = sources;
     // An LLM engine that rejects JSON Schema gets the framed contract; every other engine gets the JSON object.
     const outputMode = runnerIsLlm(runnerSpec) && !wantsJsonSchemaOutput(runnerSpec.connection) ? "framed_markdown" : "json_schema";
     const input = {
@@ -799,7 +655,6 @@ function buildReflectPromptText(args) {
         ...(assetContent !== undefined ? { assetContent } : {}),
         ...(feedback.length > 0 ? { feedback } : {}),
         ...(schemaHints.length > 0 ? { schemaHints } : {}),
-        ...(relatedLessons.length > 0 ? { relatedLessons } : {}),
         ...(options.task ? { task: options.task } : {}),
         ...(standardsContext.trim() ? { standardsContext } : {}),
         ...(options.avoidPatterns && options.avoidPatterns.length > 0 ? { avoidPatterns: options.avoidPatterns } : {}),
@@ -881,60 +736,36 @@ async function runReflectRefineIterations(args) {
     }
     return result;
 }
-/** The proposal payload from a successful run: the JSON payload on stdout. */
-function resolveReflectPayload(run, result) {
-    const { options } = run;
-    try {
-        return { payload: parseAgentProposalPayload(result.stdout ?? "") };
-    }
-    catch (err) {
-        run.emitFailed("parse_error", "parse_error", options.ref, {
-            ...exitCodeMeta(result),
-            ...(reflectTelemetry(result) ?? {}),
-        });
-        return {
-            failure: reflectFailure(run, result, "parse_error", err instanceof Error ? err.message : String(err), true),
-        };
-    }
-}
 const NOISE_SUBREASONS = {
     noop: "reflect_skipped_noop",
     cosmetic: "reflect_skipped_cosmetic",
     "low-value": "reflect_skipped_low_value",
 };
 /**
- * Sanitize, drop a no-op/cosmetic (and optionally low-value) change, judge the
- * exact content that would be persisted, then mint. A judge pass is staged only
- * when the body is unchanged: a body edit the judge passes, or one made with the
- * gate off, waits for review. Size-flagged or truncation-leaking content skips
- * the judge and waits for review.
+ * Apply the patch, drop a no-op/cosmetic (and optionally low-value) change,
+ * judge the exact content that would be persisted, then mint. A revision with a
+ * deterministic defect is refused before the judge runs, whether or not the
+ * gate is on.
  */
 async function finalizeReflectProposal(args) {
-    const { run, assetContent, result, judge, feedback } = args;
+    const { run, payload, assetContent, result, judge, feedback } = args;
     const { options } = run;
     const telemetry = reflectTelemetry(result) ?? {};
-    const sanitized = sanitizeReflectPayload({ content: args.payload.content, ...(args.payload.frontmatter ? { frontmatter: args.payload.frontmatter } : {}) }, assetContent, args.payload.ref);
-    const payload = {
-        ...args.payload,
-        content: sanitized.content,
-        ...(sanitized.frontmatter ? { frontmatter: sanitized.frontmatter } : {}),
-    };
-    if (assetContent !== undefined) {
-        const changeKind = classifyReflectChange(assetContent, payload.content);
-        if (changeKind === "noop" ||
-            changeKind === "cosmetic" ||
-            (changeKind === "low-value" && options.lowValueFilter === true)) {
-            run.emitFailed("no_change", NOISE_SUBREASONS[changeKind], options.ref, { changeKind, ...telemetry });
-            const what = changeKind === "noop"
-                ? "identical to the current asset (empty diff)"
-                : changeKind === "low-value"
-                    ? "a low-value prose micro-rewrite (few changed tokens, no structural changes)"
-                    : "a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes)";
-            return reflectFailure(run, result, "no_change", `Reflect skipped: proposed content for ${payload.ref} is ${what}; no proposal created.`, false);
-        }
+    const patched = applyReflectPatch(payload.patch, assetContent, payload.ref);
+    // A patch that changes nothing leaves the asset as it is: an empty diff.
+    const content = patched?.content ?? assetContent;
+    const changeKind = classifyReflectChange(assetContent, content);
+    if (changeKind === "noop" ||
+        changeKind === "cosmetic" ||
+        (changeKind === "low-value" && options.lowValueFilter === true)) {
+        run.emitFailed("no_change", NOISE_SUBREASONS[changeKind], options.ref, { changeKind, ...telemetry });
+        const what = changeKind === "noop"
+            ? "identical to the current asset (empty diff)"
+            : changeKind === "low-value"
+                ? "a low-value prose micro-rewrite (few changed tokens, no structural changes)"
+                : "a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes)";
+        return reflectFailure(run, result, "no_change", `Reflect skipped: proposed content for ${payload.ref} is ${what}; no proposal created.`, false);
     }
-    const flagged = Boolean(sanitized.sizeGuardRatio || sanitized.truncationMarkerLeaked);
-    const judged = judge.enabled && !flagged;
     /** A judge refused the revision: record it for the ledger's rejection window and stop. */
     const refuse = (detail, metadata, message) => {
         if (options.ref) {
@@ -953,11 +784,16 @@ async function finalizeReflectProposal(args) {
         }, options.eventsCtx);
         return reflectFailure(run, result, "quality_rejected", message, false);
     };
+    // A defect no judge needs to weigh is refused before any judge call, whether or not the gate is on.
+    const defect = findReflectDefect(assetContent, content, options.defectFilter);
+    if (defect)
+        return refuse(defect, { reflectDefect: defect }, `Reflect proposal refused before the judge: ${defect}`);
     let verdict;
     let judgeFailed = false;
-    if (judged) {
-        verdict = await runReflectQualityJudge(run.config, payload.content, assetContent ?? "", feedback, options.chat, {
+    if (judge.enabled) {
+        verdict = await runReflectQualityJudge(run.config, content, assetContent, feedback, options.chat, {
             runnerSelectionFrozen: true,
+            ref: payload.ref,
             ...(judge.runner ? { llmRunner: judge.runner } : {}),
             ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
             ...(options.signal ? { signal: options.signal } : {}),
@@ -973,12 +809,12 @@ async function finalizeReflectProposal(args) {
             }, `Reflect proposal quality gate rejected: score=${verdict.score}, reason="${verdict.reason}"`);
         }
     }
-    // #722: a rewrite of an existing asset must not grade lower on its own retrieval queries.
-    if (verdict?.pass && judge.runner && assetContent !== undefined) {
+    // #722: a revision of an existing asset must not grade lower on its own retrieval queries.
+    if (verdict?.pass && judge.runner) {
         const retrieval = await runRetrievalRegressionGate({
             ref: payload.ref,
             before: assetContent,
-            after: payload.content,
+            after: content,
             queries: loadRetrievalQueries({ proposalsCtx: options.ctx, eventsCtx: options.eventsCtx }, payload.ref),
             runner: judge.runner,
             ...(options.chat ? { chat: options.chat } : {}),
@@ -995,33 +831,17 @@ async function finalizeReflectProposal(args) {
             }, `Reflect proposal refused: ${retrieval.reason}`);
         }
     }
-    // A lesson reflect wrote is marked so a later reflect on the same skill does
-    // not read it back as independent evidence.
-    const frontmatter = {
-        ...(payload.frontmatter ?? {}),
-        ...(lenientRefType(payload.ref) === "lesson" ? { derived_from_reflect: true } : {}),
-    };
     const reviewReasons = [
         ...(judge.skippedNoJudge ? ["no-judge-configured"] : []),
         ...(judgeFailed ? ["judge-error"] : []),
-        ...(sanitized.sizeGuardRatio ? ["reflect-size-ratio"] : []),
-        ...(sanitized.truncationMarkerLeaked ? ["reflect-truncation-leak"] : []),
     ];
-    // A revision that changes the body is never auto-accepted: on labelled edits, the judge's
-    // passes on body edits were good 12 times in 37, and on frontmatter-only edits 13 in 13.
-    // One that nothing above holds for review (the judge passed it, or the gate is off) waits
-    // for a person, as does a revision with no source to compare.
-    const bodyOf = (content) => splitFrontmatter(content).body.replace(/\s+/g, " ").trim();
-    const bodyEdit = reviewReasons.length === 0 && (assetContent === undefined || bodyOf(assetContent) !== bodyOf(payload.content));
-    if (bodyEdit)
-        reviewReasons.push("body-edit");
     const proposal = mintProposal(run.stash, options.ctx, {
         ref: payload.ref,
         ...(options.target ? { target: options.target } : {}),
         source: "reflect",
         sourceRun: `reflect-${Date.now()}`,
-        payload: { content: payload.content, ...(Object.keys(frontmatter).length > 0 ? { frontmatter } : {}) },
-        ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
+        payload: { content, ...(patched?.frontmatter ? { frontmatter: patched.frontmatter } : {}) },
+        confidence: payload.confidence,
         ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
         ...(options.itemRef ? { itemRef: options.itemRef, attemptedRefs: [options.itemRef] } : {}),
     }, reviewReasons.length > 0
@@ -1030,10 +850,6 @@ async function finalizeReflectProposal(args) {
                 reason: reviewReasons.join("+"),
                 // The quality gate's hand-off to a person, as distill's: the triage drain leaves it alone.
                 gate: judgeFailed ? "quality-gate" : "reflect",
-                ...(sanitized.sizeGuardRatio ? { measured: Math.round(sanitized.sizeGuardRatio.ratio * 100) } : {}),
-                // The reviewer sees why the judge passed it (with the gate off, nothing judged it).
-                ...(bodyEdit && verdict?.criteria ? { scores: verdict.criteria } : {}),
-                ...(bodyEdit && verdict ? { judgeReason: verdict.reason } : {}),
             },
         }
         : { judged: verdict });
@@ -1046,10 +862,6 @@ async function finalizeReflectProposal(args) {
             engine: run.engineName,
             ...(judge.skippedNoJudge ? { qualityGateSkippedNoJudge: true } : {}),
             ...(judgeFailed ? { qualityReason: verdict?.reason } : {}),
-            ...(sanitized.sizeGuardRatio
-                ? { sizeGuardRatio: sanitized.sizeGuardRatio.code, sizeGuardRatioValue: sanitized.sizeGuardRatio.ratio }
-                : {}),
-            ...(sanitized.truncationMarkerLeaked ? { truncationMarkerLeaked: true } : {}),
             ...telemetry,
         },
     }, options.eventsCtx);
@@ -1079,7 +891,7 @@ export async function renderReflectPromptPreview(options) {
         throw new UsageError((!failure.ok && failure.error) || `Reflect cannot preview ref "${ref}".`, "INVALID_FLAG_VALUE");
     }
     const { runnerSpec, engineName } = resolveReflectRunner(options);
-    const sources = await gatherReflectPromptSources(options, stash, source.parsedRef, source.assetContent);
+    const sources = gatherReflectPromptSources(options, stash, source.parsedRef, source.assetContent);
     const { prompt } = buildReflectPromptText({
         options,
         parsedRef: source.parsedRef,
@@ -1126,7 +938,7 @@ export async function akmReflect(options = {}) {
     preflightReflectDispatch(runnerSpec, notices.add);
     if (judgeRunner && judgeRunner !== runnerSpec)
         preflightReflectDispatch(judgeRunner, notices.add);
-    const sources = await gatherReflectPromptSources(options, stash, parsedRef, assetContent);
+    const sources = gatherReflectPromptSources(options, stash, parsedRef, assetContent);
     const agentEnv = options.eventSource === "improve" ? { AKM_EVENT_SOURCE: "improve" } : {};
     const sensitiveValues = collectDispatchSensitiveValues(runnerSpec, {
         ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
@@ -1163,25 +975,30 @@ export async function akmReflect(options = {}) {
             });
             return { ...envelope, ...notices.fields() };
         }
-        const resolved = resolveReflectPayload(run, result);
-        if ("failure" in resolved)
-            return resolved.failure;
-        payload = resolved.payload;
+        // The iteration parsed the reply and put its payload on stdout.
+        payload = JSON.parse(result.stdout);
     }
     catch (error) {
         if (!(error instanceof ConfigError))
             emitInvoked();
         throw error;
     }
-    const unsafeContent = generatedContentRejection(payload.content, redactSensitiveText(payload.content, sensitiveValues));
+    const generated = Object.values(payload.patch).join("\n");
+    const unsafeContent = generatedContentRejection(generated, redactSensitiveText(generated, sensitiveValues));
     if (unsafeContent) {
         emitFailed("parse_error", "parse_error", options.ref, exitCodeMeta(result));
         return reflectFailure(run, result, "parse_error", unsafeContent, false);
     }
+    // An unscoped reply names its asset only now: read it as a targeted run read its own before dispatch.
+    const target = options.ref
+        ? { assetContent }
+        : await resolveReflectSource({ ...options, ref: payload.ref }, stash, emitFailed);
+    if ("failure" in target)
+        return target.failure;
     return finalizeReflectProposal({
         run,
         payload,
-        assetContent,
+        assetContent: target.assetContent ?? "",
         result,
         judge: { enabled: judgeWanted && !skippedNoJudge, skippedNoJudge, runner: judgeRunner },
         feedback: sources.feedback,