akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/commands/improve/reflect.js

@@ -11,7 +11,7 @@
  *      content. Pull recent feedback (`feedback` events for that ref) and
  *      lesson-lint findings to surface as schema hints.
  *   3. Build the prompt via {@link buildReflectPrompt}.
- *   4. Spawn the configured agent profile via {@link runAgent}.
+ *   4. Dispatch the selected named engine via {@link executeRunner}.
  *   5. Parse the agent's stdout into a {@link AgentProposalPayload}.
  *   6. Insert into the proposal queue via {@link createProposal} with
  *      `source: "reflect"`.
@@ -24,32 +24,36 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { parseAssetRef } from "../../core/asset/asset-ref.js";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { stripMarkdownFences } from "../../core/asset/markdown.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
-import { resolveStashDir } from "../../core/common.js";
-import { getImproveProcessConfig, loadConfig } from "../../core/config/config.js";
-import { ConfigError, UsageError } from "../../core/errors.js";
+import { loadConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
 import { appendEvent, readEvents } from "../../core/events.js";
 import { lintLessonContent } from "../../core/lesson-lint.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
-import { warn } from "../../core/warn.js";
 import { lookup } from "../../indexer/indexer.js";
-import { runAgent, } from "../../integrations/agent/index.js";
-import { resolveProcessAgentProfile } from "../../integrations/agent/config.js";
-import { buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
-import { resolveDefaultLlmRunner, resolveImproveProcessRunnerFromProfile, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
-import { executeRunner } from "../../integrations/agent/runner-dispatch.js";
-import { runOpencodeSdk } from "../../integrations/harnesses/opencode-sdk/index.js";
-import { chatCompletion } from "../../llm/client.js";
-import { isLlmFeatureEnabled } from "../../llm/feature-gate.js";
-import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigFromDisk, resolveAgentProfile, } from "../agent/agent-support.js";
-import { createProposal, isProposalSkipped, listProposals, } from "../proposal/repository.js";
+import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
+import { buildReflectOutputRepairPrompt, buildReflectPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "../../integrations/agent/prompts.js";
+import { materializeLlmRunnerConnection, resolveImproveProcessRunner, runnerIsLlm, runnerSupportsFileWrite, } from "../../integrations/agent/runner.js";
+import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
+import { LlmCallError } from "../../llm/client.js";
+import { callStructured } from "../../llm/structured-call.js";
+import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
+import { isProposalSkipped, listProposals, proposalContent, } from "../proposal/repository.js";
 import { checkReflectSize, isValidDescription } from "../proposal/validators/proposal-quality-validators.js";
-import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
+import { deriveLessonRef } from "./distill.js";
+import { runReflectQualityJudge } from "./distill/quality-gate.js";
+import { findAssetFilePath } from "./eligibility.js";
+import { emitProposal } from "./proposal-envelope.js";
 import { classifyReflectChange } from "./reflect-noise.js";
+import { createRunContext, resolveRunStashDir } from "./run-context.js";
+import { MAX_REJECTED_PROPOSALS } from "./shared.js";
+import { durableImproveRef, improveStateReadRefs } from "./source-identity.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -60,10 +64,10 @@ const MAX_GLOBAL_FEEDBACK_LINES = 20;
  */
 function readRecentFeedback(ref) {
     try {
-        const result = readEvents({ type: "feedback", ...(ref ? { ref } : {}) });
+        const events = readEvents({ type: "feedback", ...(ref ? { ref } : {}) }).events;
         const lines = [];
         const limit = ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES;
-        for (const event of result.events.slice(-limit)) {
+        for (const event of events.slice(-limit)) {
             const md = (event.metadata ?? {});
             const signal = typeof md.signal === "string" ? md.signal : "?";
             const note = typeof md.reason === "string" ? md.reason : typeof md.note === "string" ? md.note : "";
@@ -76,7 +80,6 @@ function readRecentFeedback(ref) {
         return [];
     }
 }
-const MAX_REJECTED_PROPOSALS = 3;
 /**
  * Asset types that reflect is allowed to operate on.
  *
@@ -97,7 +100,6 @@ export const REFLECT_ALLOWED_TYPES = new Set([
     "knowledge",
     "memory",
     "lesson",
-    "wiki",
     "skill",
     "agent",
     "command",
@@ -112,7 +114,7 @@ export const REFLECT_ALLOWED_TYPES = new Set([
  * LLM tried to rewrite them.
  *
  * Observed regression: proposal `26941510` (May 2026) renamed
- * `skill:openpalm-stack-diagnostics`'s `name` field to `"diagnostic-checklist"`.
+ * `skills/openpalm-stack-diagnostics`'s `name` field to `"diagnostic-checklist"`.
  */
 const PROTECTED_FRONTMATTER_FIELDS = new Set(["name", "ref", "id", "slug", "type"]);
 /**
@@ -132,7 +134,7 @@ function readRejectedProposals(stash, ref) {
             .map((p) => ({
             ref: p.ref,
             reason: p.review?.reason ?? "no reason given",
-            contentPreview: p.payload.content.slice(0, 500),
+            contentPreview: proposalContent(p).slice(0, 500),
         }));
     }
     catch {
@@ -142,19 +144,20 @@ function readRejectedProposals(stash, ref) {
 /**
  * Synthesize a tmp draft-file path for the agent/sdk file-write contract.
  *
- * Mirrors `src/commands/propose.ts:163-178` — when the runner is agent-CLI or
- * the OpenCode SDK, we instruct the agent to write the proposal body directly
- * to this file instead of inlining it in JSON on stdout. This bypasses two
+ * Mirrors the draft-path synthesis in `src/commands/proposal/propose.ts` —
+ * when the runner is agent-CLI or the OpenCode SDK, we instruct the agent to
+ * write the proposal body directly to this file instead of inlining it in
+ * JSON on stdout. This bypasses two
  * known failure modes for long assets: (a) ARG_MAX truncation on prompt
  * round-trips through fenced JSON, and (b) embedded-JSON parser brittleness
- * on multi-KB bodies (e.g. the `knowledge:systems/KOKORO_USAGE_GUIDE` 8.4KB
+ * on multi-KB bodies (e.g. the `knowledge/systems/KOKORO_USAGE_GUIDE` 8.4KB
  * payload that produced 4/5 `parse_error` in May 2026 reflect validation).
  *
  * The path lives under {@link os.tmpdir} and embeds the (sanitized) ref +
  * timestamp + random suffix so concurrent reflect calls cannot collide.
  *
- * Returns `undefined` for the LLM HTTP runner — the chat-completion transport
- * has no filesystem access (see warning at `src/llm/call-ai.ts:64-71`).
+ * The LLM HTTP runner cannot use this path because chat-completion transport
+ * has no filesystem access.
  */
 function synthesizeReflectDraftPath(ref) {
     const safeRef = (ref ?? "no-ref").replace(/[^a-z0-9_-]/gi, "_");
@@ -190,22 +193,27 @@ function hasRelatedSkillSource(content, skillRef) {
     const sources = parsed.data.sources;
     return Array.isArray(sources) && sources.some((source) => typeof source === "string" && source.trim() === skillRef);
 }
-async function readRelatedLessons(stash, ref, parsedRef) {
+async function readRelatedLessons(ctx, stash, ref, parsedRef, itemRef) {
     if (parsedRef.type !== "skill")
         return [];
     const related = new Map();
     const derivedLessonRef = deriveLessonRef(ref);
     const candidateRefs = new Set([derivedLessonRef]);
-    const derivedLessonPath = path.join(stash, "lessons", `${derivedLessonRef.slice("lesson:".length)}.md`);
+    const derivedLessonPath = path.join(stash, "lessons", `${parseRefInput(derivedLessonRef).name}.md`);
     if (fs.existsSync(derivedLessonPath)) {
-        related.set(derivedLessonRef, { ref: derivedLessonRef, content: fs.readFileSync(derivedLessonPath, "utf8") });
+        // WI-9.10: genuine content read — routed through the per-invocation asset
+        // memo (D6). No write to this same path happens later in this invocation,
+        // so memoizing is safe (see run-context.ts's D6 seam docblock).
+        related.set(derivedLessonRef, { ref: derivedLessonRef, content: ctx.readAsset(derivedLessonPath) });
     }
     try {
-        const feedbackEvents = readEvents({ type: "distill_invoked", ref }).events;
+        // Match events using the candidate's single durable state key.
+        const distillInvokedKeys = new Set(improveStateReadRefs(ref, itemRef));
+        const feedbackEvents = readEvents({ type: "distill_invoked" }).events.filter((event) => event.ref !== undefined && distillInvokedKeys.has(event.ref));
         for (const event of feedbackEvents) {
-            const lessonRef = typeof event.metadata?.lessonRef === "string" ? event.metadata.lessonRef : undefined;
-            if (lessonRef?.startsWith("lesson:"))
-                candidateRefs.add(lessonRef);
+            const proposalRef = typeof event.metadata?.proposalRef === "string" ? event.metadata.proposalRef : undefined;
+            if (proposalRef && lenientRefType(proposalRef) === "lesson")
+                candidateRefs.add(proposalRef);
         }
     }
     catch {
@@ -213,10 +221,10 @@ async function readRelatedLessons(stash, ref, parsedRef) {
     }
     for (const candidateRef of candidateRefs) {
         try {
-            const entry = await lookup(parseAssetRef(candidateRef));
-            if (!entry?.filePath || !fs.existsSync(entry.filePath))
+            const filePath = await findAssetFilePath(durableImproveRef(candidateRef), stash);
+            if (!filePath || !fs.existsSync(filePath))
                 continue;
-            const content = fs.readFileSync(entry.filePath, "utf8");
+            const content = ctx.readAsset(filePath);
             related.set(candidateRef, { ref: candidateRef, content });
         }
         catch {
@@ -229,11 +237,11 @@ async function readRelatedLessons(stash, ref, parsedRef) {
             for (const fileName of fs.readdirSync(lessonsDir)) {
                 if (!fileName.endsWith(".md"))
                     continue;
-                const content = fs.readFileSync(path.join(lessonsDir, fileName), "utf8");
+                const content = ctx.readAsset(path.join(lessonsDir, fileName));
                 if (!hasRelatedSkillSource(content, ref))
                     continue;
                 const lessonName = fileName.slice(0, -3);
-                const lessonRef = `lesson:${lessonName}`;
+                const lessonRef = conceptIdFromTypeName("lesson", lessonName);
                 if (!related.has(lessonRef)) {
                     related.set(lessonRef, { ref: lessonRef, content });
                 }
@@ -283,97 +291,38 @@ async function readRelatedLessons(stash, ref, parsedRef) {
 /**
  * Returns true only when `stdout` is a recognised AKM proposal-skip signal.
  *
- * Two accepted forms:
- *  1. Structured JSON: `{ skipped: true }` or `{ reason: "<known-skip-reason>" }`
- *  2. Legacy text: any line matching `/proposal skipped/i`
- *
- * The previous regex `/cooldown/i` was intentionally broadened to avoid
- * false-positives on real agent error messages that incidentally contain the
- * word "cooldown" (e.g. "rate limit cooldown exceeded"). Only the tightly
- * scoped forms above are treated as legitimate skip signals.
+ * Accepted forms are structured JSON: `{ skipped: true }` or
+ * `{ reason: "<known-skip-reason>" }`.
  */
 function isStructuredCooldownSignal(stdout) {
     try {
         const parsed = JSON.parse(stdout.trim());
         if (parsed?.skipped === true)
             return true;
-        if (typeof parsed?.reason === "string" &&
-            ["duplicate_pending", "content_hash_match", "cooldown", "below_threshold"].includes(parsed.reason))
+        if (typeof parsed?.reason === "string" && ["fingerprint_match", "rejection_backoff"].includes(parsed.reason))
             return true;
     }
     catch {
         // Non-JSON stdout is never a structured cooldown signal.
     }
-    // Legacy text signal emitted by older proposal output lines.
-    return /proposal skipped/i.test(stdout);
+    return false;
 }
 /**
- * Fallback payload parser for reflect agent stdout (R-6 / #375).
- *
- * When the agent does not emit valid JSON (old-style agents, SDK mode without
- * structured output support), this function attempts to recover a proposal
- * payload from the raw markdown output. The parser is deliberately strict —
- * it requires the content to have a complete proposal structure (frontmatter
- * with required fields or a full heading + body).
- *
- * Strictness rationale: The previous implementation accepted any markdown
- * starting with `#` or `---`, which admitted malformed / hallucinated content
- * as valid proposals. Anthropic agent best practices recommend structured
- * output when the SDK supports it; this tighter fallback is the safety net.
- *
- * When `sdkMode === true`, structured output (tool-call schema) should be used
- * instead of this fallback. That wiring is tracked separately (full SDK
- * structured-output integration); for now this tighter parser applies to all
- * modes and is the primary R-6 deliverable.
+ * Best-effort asset type for a maybe-ref string, in the 0.9.0 `[bundle//]conceptId`
+ * grammar (`""` when it does not parse). Replaces the pre-0.9.0 `ref.split(":")[0]`
+ * type-extraction, which yielded the whole conceptId (`lessons/my-lesson`) instead
+ * of the type once refs stopped carrying a `type:` prefix (ref-grammar decision
+ * D-R3). Lenient by design — the callers degrade gracefully on an empty type.
  */
-function fallbackPayloadFromRawContent(stdout, ref, sdkMode = false) {
+function lenientRefType(ref) {
     if (!ref)
-        return undefined;
-    const trimmed = stripMarkdownFences(stdout).trim();
-    if (!trimmed)
-        return undefined;
-    const targetType = ref.split(":")[0];
-    if (!looksLikeAssetContent(trimmed, sdkMode, targetType))
-        return undefined;
-    return { ref, content: trimmed };
-}
-/**
- * Determine whether raw agent output looks like a valid asset payload (R-6 / #375).
- *
- * Tightened from the previous `startsWith("#") || startsWith("---")`:
- *
- * - YAML frontmatter (`---`): must contain a `description:` field (the only
- *   required frontmatter key in v1 spec). This eliminates empty `---\n---\n`
- *   blocks and pure delimiter sequences as valid payloads.
- * - Heading start (`#`): must have at least 3 non-blank lines after the heading,
- *   to ensure there is actual body content and not just a title stub.
- * - In SDK mode (`sdkMode === true`): additionally requires `when_to_use:` for
- *   lesson types (full structured output will replace this in a future PR).
- */
-function looksLikeAssetContent(value, sdkMode = false, targetType) {
-    if (value.startsWith("---")) {
-        // YAML frontmatter must contain at least a description field.
-        const fmEnd = value.indexOf("\n---", 4);
-        if (fmEnd === -1)
-            return false;
-        const fmBlock = value.slice(0, fmEnd + 4);
-        const hasDescription = /^description\s*:/m.test(fmBlock);
-        if (!hasDescription)
-            return false;
-        // In SDK mode, lesson assets additionally require a when_to_use field.
-        // Use the target ref type rather than frontmatter type: (which is non-standard).
-        if (sdkMode && targetType === "lesson") {
-            return /^when_to_use\s*:/m.test(fmBlock);
-        }
-        return true;
+        return "";
+    try {
+        return parseRefInput(ref).type;
     }
-    if (value.startsWith("#")) {
-        // Heading + at least 2 non-blank lines (heading + at least one body line).
-        // This rejects pure title stubs (`# Title\n`) but accepts minimal valid content.
-        const lines = value.split("\n").filter((l) => l.trim().length > 0);
-        return lines.length >= 2;
+    catch {
+        return "";
     }
-    return false;
 }
 /**
  * Split a markdown blob into `[frontmatterText, bodyText]`.
@@ -565,7 +514,7 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
     //   - a present-but-otherwise-invalid description exists (too short, a heading
     //     fragment) — overwriting authored content is out of scope; the prompt
     //     instruction handles improving it instead.
-    const refType = targetRef.includes(":") ? (targetRef.split(":")[0] ?? "") : "";
+    const refType = lenientRefType(targetRef);
     const mergedDesc = mergedFm.description;
     const descIsMissing = typeof mergedDesc !== "string" || mergedDesc.trim().length === 0;
     const sourceHadFrontmatter = sourceFmText !== null && Object.keys(sourceFm).length > 0;
@@ -616,298 +565,936 @@ export function sanitizeReflectPayload(payload, sourceContent, targetRef) {
 /**
  * JSON Schema for structured reflect output. Passed to `chatCompletion` when
  * the connection has `supportsJsonSchema: true` so the model returns a strict
- * JSON object matching {@link AgentProposalPayload}.
+ * JSON object containing only the target-scoped fields AKM cannot derive.
  */
+const REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA = {
+    type: "object",
+    required: ["description", "when_to_use"],
+    additionalProperties: false,
+    properties: {
+        description: { type: ["string", "null"] },
+        when_to_use: { type: ["string", "null"] },
+    },
+};
 export const REFLECT_JSON_SCHEMA = {
     type: "object",
-    required: ["ref", "content"],
+    required: ["content", "confidence", "frontmatterPatch"],
     additionalProperties: false,
     properties: {
-        ref: { type: "string", description: "Asset ref in type:name format (e.g. lesson:my-lesson)." },
-        content: { type: "string", description: "Full markdown content for the asset." },
-        frontmatter: {
-            type: "object",
-            description: "Optional frontmatter key-value pairs to merge into the asset.",
-            additionalProperties: true,
-        },
+        content: { type: "string", description: "Complete improved markdown body without YAML frontmatter." },
         // Phase 6A (Advantage D6a): self-reported confidence in [0, 1]. When the
         // LLM is well-calibrated, scores at or above the configured threshold
         // (default 0.8) drive auto-accept in `akm improve`. Out-of-range or
-        // non-finite values are clamped/dropped by the parser — the schema keeps
-        // the field optional so older agents that don't emit a score still work.
+        // non-finite values are rejected by direct-output extraction. Agent and SDK
+        // confidence remains optional on their separate existing contracts.
+        confidence: {
+            type: "number",
+            minimum: 0,
+            maximum: 1,
+            description: "Self-reported quality confidence in [0, 1]. Persisted on the proposal for reviewers and the triage judge to read during adjudication.",
+        },
+        frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
+    },
+};
+const REFLECT_UNSCOPED_JSON_SCHEMA = {
+    type: "object",
+    required: ["ref", "content", "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: "Optional self-reported quality confidence in [0, 1]. Proposals with confidence >= the active threshold (default 0.8) may be auto-accepted by `akm improve`.",
+            description: "Self-reported quality confidence in [0, 1].",
         },
+        frontmatterPatch: REFLECT_FRONTMATTER_PATCH_JSON_SCHEMA,
     },
 };
 /** Critique prompt injected between prior draft and refinement request (Self-Refine loop). */
-const REFLECT_CRITIQUE_PROMPT = "Your previous proposal is shown above. Please review it critically and provide an improved version that is more specific, actionable, and avoids any issues with the previous attempt. Return only the improved JSON proposal.";
+const REFLECT_CRITIQUE_PROMPT = "Your previous proposal is shown above. Review it critically and provide an improved version that is more specific, actionable, and avoids any issues with the previous attempt. Return only the improved response using the output contract from the original prompt.";
+function reflectLlmTelemetry(result) {
+    if (!result.parsed || typeof result.parsed !== "object" || Array.isArray(result.parsed))
+        return undefined;
+    const parsed = result.parsed;
+    if (parsed.outputMode !== "json_schema" && parsed.outputMode !== "framed_markdown")
+        return undefined;
+    if (typeof parsed.repairAttempts !== "number")
+        return undefined;
+    return { outputMode: parsed.outputMode, repairAttempts: parsed.repairAttempts };
+}
+function reflectLlmPriorDraft(result) {
+    if (!result.parsed || typeof result.parsed !== "object" || Array.isArray(result.parsed))
+        return undefined;
+    const priorDraft = result.parsed.priorDraft;
+    return typeof priorDraft === "string" ? priorDraft : undefined;
+}
+function parseReflectConfidence(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error('direct reflect response missing required number field "confidence" in [0, 1]');
+    }
+    return value;
+}
+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 frontmatter = {};
+    for (const field of ["description", "when_to_use"]) {
+        const fieldValue = patch[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();
+    }
+    return Object.keys(frontmatter).length > 0 ? frontmatter : undefined;
+}
+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 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 } : {}),
+    };
+}
+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 confidenceLine = headerLines.find((line) => line.startsWith("AKM_REFLECT_CONFIDENCE:"));
+    const refLine = headerLines.find((line) => line.startsWith("AKM_REFLECT_REF:"));
+    const patchLine = headerLines.find((line) => line.startsWith("AKM_REFLECT_FRONTMATTER_PATCH:"));
+    const expectedHeaderLines = targetRef ? 2 : 3;
+    const invalidRefLine = targetRef ? refLine !== undefined : refLine === undefined;
+    if (headerLines.length !== expectedHeaderLines || !confidenceLine || !patchLine || invalidRefLine) {
+        throw new Error("direct reflect response contained invalid frame metadata");
+    }
+    const confidenceText = confidenceLine.slice("AKM_REFLECT_CONFIDENCE:".length).trim();
+    if (!/^(?:0(?:\.\d+)?|1(?:\.0+)?)$/.test(confidenceText)) {
+        throw new Error("direct reflect frame confidence must be a decimal number in [0, 1]");
+    }
+    const confidence = parseReflectConfidence(Number(confidenceText));
+    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");
+    const patchText = patchLine.slice("AKM_REFLECT_FRONTMATTER_PATCH:".length).trim();
+    let parsedPatch;
+    try {
+        parsedPatch = JSON.parse(patchText);
+    }
+    catch {
+        throw new Error("direct reflect response contained invalid frontmatter patch JSON");
+    }
+    const frontmatter = parseReflectFrontmatterPatch(parsedPatch);
+    return { ref, content, confidence, ...(frontmatter ? { frontmatter } : {}) };
+}
+function parseDirectReflectOutput(raw, mode, targetRef) {
+    return mode === "json_schema" ? parseSchemaReflectOutput(raw, targetRef) : parseFramedReflectOutput(raw, targetRef);
+}
 /**
  * Run a single reflect iteration directly via the LLM API (v2 config path).
  *
  * Returns an {@link AgentRunResult}-shaped object so it can slot into the same
- * dispatch loop as agent-based runners. On success, `stdout` contains the raw
- * LLM response (unparsed JSON or prose). On failure, the error is captured
- * into the result rather than thrown.
+ * dispatch loop as agent-based runners. Production calls extract the selected
+ * direct-LLM contract and normalize it to proposal JSON in `stdout`. Errors
+ * are captured into the result rather than thrown.
  */
 export async function runReflectViaLlm(opts) {
     const start = Date.now();
+    let repairAttempts = 0;
     const messages = [{ role: "user", content: opts.prompt ?? "" }];
+    const configuredTimeout = Object.hasOwn(opts, "timeoutMs")
+        ? (opts.timeoutMs ?? null)
+        : Object.hasOwn(opts.connection, "timeoutMs")
+            ? (opts.connection.timeoutMs ?? null)
+            : DEFAULT_LLM_TIMEOUT_MS;
+    const deadline = typeof configuredTimeout === "number" ? start + configuredTimeout : undefined;
     if (opts.priorDraft !== undefined && opts.iteration > 0) {
         messages.push({ role: "assistant", content: opts.priorDraft });
         messages.push({ role: "user", content: REFLECT_CRITIQUE_PROMPT });
     }
+    const call = async (callMessages, repairTimeoutMs) => callStructured({
+        feature: "reflect_proposal",
+        config: opts.connection,
+        messages: callMessages,
+        request: {
+            ...(repairTimeoutMs !== undefined
+                ? { timeoutMs: repairTimeoutMs }
+                : Object.hasOwn(opts, "timeoutMs")
+                    ? { timeoutMs: opts.timeoutMs }
+                    : {}),
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            ...(opts.responseSchema !== undefined ? { responseSchema: opts.responseSchema } : {}),
+            ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
+            // Reflect requires a machine-readable payload. Visible chain-of-thought
+            // can consume the output cap before the model reaches the envelope.
+            enableThinking: false,
+            ...(opts.chat ? { chat: opts.chat } : {}),
+        },
+        parse: (raw) => raw ?? "",
+        // Unreachable on the ungated path (errors propagate to the catch below).
+        onError: () => "",
+        fallback: "",
+    });
+    const failure = (err, reason, repairAttempts, stdout = "", exitCode = 1) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            stdout,
+            stderr: msg,
+            durationMs: Date.now() - start,
+            exitCode,
+            reason,
+            error: msg,
+            parsed: { outputMode: opts.outputMode, repairAttempts },
+        };
+    };
     try {
-        let stdout;
-        if (opts.chat) {
-            // Test seam: injected chat function (two-arg signature, no responseSchema).
-            stdout = await opts.chat(opts.connection, messages);
+        if (opts.signal?.aborted)
+            throw new Error("Reflect request aborted");
+        const stdout = await call(messages);
+        let payload;
+        let acceptedOutput = stdout;
+        try {
+            payload = parseDirectReflectOutput(stdout, opts.outputMode, opts.targetRef);
         }
-        else {
-            // Production path: full chatCompletion with optional structured-output schema
-            // and optional hard max_tokens cap (derived from source body size).
-            stdout = await chatCompletion(opts.connection, messages, {
-                ...(opts.responseSchema !== undefined ? { responseSchema: opts.responseSchema } : {}),
-                ...(opts.maxTokens !== undefined ? { maxTokens: opts.maxTokens } : {}),
-            });
+        catch (err) {
+            if (opts.allowRepair === false)
+                return failure(err, "parse_error", 0, stdout, 0);
+            if (opts.signal?.aborted)
+                return failure(new Error("Reflect request aborted"), "aborted", 0, stdout);
+            const remaining = deadline === undefined ? undefined : deadline - Date.now();
+            if (remaining !== undefined && remaining <= 0) {
+                return failure(new LlmCallError("Reflect request timed out before output repair", "timeout"), "timeout", 0, stdout);
+            }
+            repairAttempts = 1;
+            const repairMessages = [
+                ...messages,
+                { role: "assistant", content: stdout },
+                {
+                    role: "user",
+                    content: buildReflectOutputRepairPrompt(opts.outputMode, opts.targetRef !== undefined),
+                },
+            ];
+            const repaired = await call(repairMessages, remaining);
+            acceptedOutput = repaired;
+            try {
+                payload = parseDirectReflectOutput(repaired, opts.outputMode, opts.targetRef);
+            }
+            catch (err) {
+                return failure(err, "parse_error", repairAttempts, repaired, 0);
+            }
         }
         return {
             ok: true,
-            stdout,
+            stdout: JSON.stringify(payload),
             stderr: "",
             durationMs: Date.now() - start,
             exitCode: 0,
+            parsed: { outputMode: opts.outputMode, repairAttempts, priorDraft: acceptedOutput },
         };
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            ok: false,
-            stdout: "",
-            stderr: msg,
-            durationMs: Date.now() - start,
-            exitCode: 1,
-            reason: "non_zero_exit",
-            error: msg,
-        };
+        const reason = opts.signal?.aborted
+            ? "aborted"
+            : err instanceof LlmCallError && err.code === "timeout"
+                ? "timeout"
+                : "non_zero_exit";
+        return failure(err, reason, repairAttempts);
     }
 }
-function failureEnvelope(result, ref, fallbackReason = "non_zero_exit") {
+function failureEnvelope(result, ref, engine, fallbackReason = "non_zero_exit") {
     return {
         ...baseFailureFields(result, fallbackReason),
+        schemaVersion: 2,
         ...(ref ? { ref } : {}),
+        ...(engine ? { engine } : {}),
     };
 }
-export async function akmReflect(options = {}) {
-    const stash = options.stashDir ?? resolveStashDir();
-    // 1. Always emit `reflect_invoked` at command entry — observers see the
-    // attempt regardless of downstream success/failure.
-    appendEvent({
-        eventType: "reflect_invoked",
-        ...(options.ref ? { ref: options.ref } : {}),
-        metadata: {
-            ...(options.task ? { task: options.task } : {}),
-            ...(options.profile ? { profile: options.profile } : {}),
-            // Attribution tagging: stamp the eligibility lane so reflect_invoked can be
-            // sliced by lane downstream. See EligibilitySource.
-            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
-        },
-    });
-    // Fix #3 (observability 0.8.0): every failure path below MUST emit
-    // `reflect_completed` so observers can close the invoke/complete loop. The
-    // three success-side `reflect_completed` emit sites carry rich metadata
-    // (qualityRejected, sanitized, proposalId, etc.); the failure-side emits
-    // carry `{ok: false, reason}` plus the ref when known. Stable failure
-    // reasons line up with `AgentFailureReason`: "parse_error", "non_zero_exit",
-    // "cooldown", "timeout", "spawn_failed", "llm_*", plus the synthetic
-    // "ref_mismatch" / "enoent" / "draft_missing" subtypes for cases the agent
-    // surface conflates as "parse_error". Sub-reasons land in `subreason`.
-    const emitReflectFailed = (reason, subreason, ref, extra) => {
+/**
+ * Reflect content-preservation + proposal creation: restore/reset protected
+ * frontmatter and reject unsafe body-size ratios (sanitizeReflectPayload), the
+ * #580 noise gate, the optional quality judge, then create the proposal (with
+ * the R-4/#373 lesson provenance stamp) and emit `reflect_completed`. Extracted
+ * verbatim from `akmReflect`; every reject/skip envelope and event is
+ * byte-identical.
+ */
+async function finalizeReflectProposal(args) {
+    const { assetContent, result, options, engineName, config, activeStrategy, runnerSpec, feedback, stash, emitReflectFailed, } = args;
+    let payload = args.payload;
+    const outputTelemetry = reflectLlmTelemetry(result);
+    // 7. Reflect content-preservation rails:
+    //     - Restore source frontmatter so reflect can never strip indexable
+    //       fields (`description`, `when_to_use`, `tags`, ...).
+    //     - Reset protected identity fields (`name`, `ref`, `id`, `slug`,
+    //       `type`) the LLM tried to change.
+    //     - Reject proposals that shrink/expand the body past safe ratios.
+    //
+    // See REFLECT_ALLOWED_TYPES / sanitizeReflectPayload for the underlying
+    // hypotheses + observed regressions (`8737ab63`, `26941510`, and the
+    // catastrophic-shrinkage cases from the May 2026 review).
+    const sanitizeOutcome = sanitizeReflectPayload({ content: payload.content, ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}) }, assetContent, payload.ref);
+    if (sanitizeOutcome.reject) {
         appendEvent({
             eventType: "reflect_completed",
-            ...(ref ? { ref } : {}),
+            ref: payload.ref,
             metadata: {
                 source: "reflect",
-                ok: false,
-                reason,
-                subreason,
-                ...(extra ?? {}),
+                sanitized: true,
+                rejected: true,
+                rejectReason: sanitizeOutcome.reject.error,
+                ...(sanitizeOutcome.warnings.length > 0 ? { sanitizerWarnings: sanitizeOutcome.warnings } : {}),
+                ...(outputTelemetry ?? {}),
             },
-        });
+        }, options.eventsCtx);
+        return {
+            schemaVersion: 2,
+            ok: false,
+            reason: sanitizeOutcome.reject.reason,
+            error: sanitizeOutcome.reject.error,
+            ...(options.ref ? { ref: options.ref } : {}),
+            engine: engineName,
+            exitCode: result.exitCode,
+        };
+    }
+    payload = {
+        ...payload,
+        content: sanitizeOutcome.content,
+        ...(sanitizeOutcome.frontmatter ? { frontmatter: sanitizeOutcome.frontmatter } : {}),
     };
-    // 2. Resolve target asset content (if a ref is supplied).
-    let assetContent;
-    let parsedRef;
-    if (options.ref) {
-        parsedRef = parseAssetRef(options.ref);
-        // 2a. Type guard — reflect only operates on asset types whose canonical
-        // shape is `frontmatter + markdown body`. Refuse non-markdown types
-        // (script / env / task) up-front so reflect never prepends YAML to a
-        // `.ts` file or rewrites a `.env` blob as prose. See REFLECT_ALLOWED_TYPES.
-        if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type)) {
-            // Deterministic type-guard rejection — the LLM is never invoked. Emit
-            // with reason `unsupported_type` so the improve loop can route this to
-            // the `reflect-skipped` action bucket instead of `reflect-failed`. See
-            // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1a
-            // ("Reflect refused asset type" — ~9% of reflect-failed events).
-            emitReflectFailed("unsupported_type", "unsupported_type", options.ref, { type: parsedRef.type });
+    // 7c. Noise gate (#580): never queue a proposal whose sanitized content is
+    // identical to the current asset (empty diff) or differs only cosmetically
+    // (whitespace reflow, code-fence language hints, YAML scalar re-folding).
+    // Pure deterministic text comparison — see `reflect-noise.ts`. Skipped when
+    // there is no source asset (new-asset proposals have nothing to diff against).
+    if (assetContent !== undefined) {
+        const changeKind = classifyReflectChange(assetContent, payload.content);
+        // 'low-value' is config-gated (#639). DEFAULT OFF — absent = byte-identical
+        // pre-#639 behaviour (low-value treated the same as substantive). Resolved
+        // by the caller from the active improve strategy's
+        // `processes.reflect.lowValueFilter.enabled` and passed via options, so the
+        // running strategy decides.
+        const lowValueFilterEnabled = options.lowValueFilter === true;
+        const isDeferred = changeKind === "noop" || changeKind === "cosmetic" || (changeKind === "low-value" && lowValueFilterEnabled);
+        if (isDeferred) {
+            const subreason = changeKind === "noop"
+                ? "reflect_skipped_noop"
+                : changeKind === "low-value"
+                    ? "reflect_skipped_low_value"
+                    : "reflect_skipped_cosmetic";
+            emitReflectFailed("no_change", subreason, options.ref, { changeKind, ...(outputTelemetry ?? {}) });
             return {
-                schemaVersion: 1,
+                schemaVersion: 2,
                 ok: false,
-                reason: "unsupported_type",
-                error: `Reflect refused: asset type "${parsedRef.type}" is not supported by reflect (only markdown-canonical types are allowed: ${[...REFLECT_ALLOWED_TYPES].sort().join(", ")}). Use \`akm propose\` or edit the file directly.`,
-                ref: options.ref,
-                exitCode: null,
+                reason: "no_change",
+                error: changeKind === "noop"
+                    ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
+                    : changeKind === "low-value"
+                        ? `Reflect skipped: proposed content for ${payload.ref} is a low-value prose micro-rewrite (few changed tokens, no structural changes); no proposal created.`
+                        : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                engine: engineName,
+                exitCode: result.exitCode,
             };
         }
-        if (options.assetContent !== undefined) {
-            // Test seam — caller pre-loaded the source content.
-            assetContent = options.assetContent;
-        }
-        else {
-            try {
-                const entry = await lookup(parsedRef);
-                if (entry?.filePath && fs.existsSync(entry.filePath)) {
-                    assetContent = fs.readFileSync(entry.filePath, "utf8");
-                }
-            }
-            catch {
-                // Index miss is non-fatal — the agent can still propose a fresh asset.
-            }
+    }
+    // 7c. Judge the exact sanitized content that can be persisted. Fail closed
+    // on cancellation, transport failure, malformed output, or an invalid score.
+    const qualityGateEnabled = (activeStrategy?.processes?.reflect?.qualityGate?.enabled ?? false) ||
+        (activeStrategy?.processes?.distill?.qualityGate?.enabled ?? true);
+    if (qualityGateEnabled) {
+        const judgeResult = await runReflectQualityJudge(config, payload.content, assetContent ?? "", feedback, options.chat, {
+            ...(runnerIsLlm(runnerSpec) ? { llmConfig: materializeLlmRunnerConnection(runnerSpec) } : {}),
+            ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!judgeResult.pass) {
+            appendEvent({
+                eventType: "reflect_completed",
+                ref: payload.ref,
+                metadata: {
+                    source: "reflect",
+                    qualityRejected: true,
+                    qualityScore: judgeResult.score,
+                    qualityReason: judgeResult.reason,
+                    ...(outputTelemetry ?? {}),
+                },
+            }, options.eventsCtx);
+            return {
+                schemaVersion: 2,
+                ok: false,
+                reason: "parse_error",
+                error: `Reflect proposal quality gate rejected: score=${judgeResult.score}, reason="${judgeResult.reason}"`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                engine: engineName,
+                exitCode: result.exitCode,
+            };
         }
     }
-    // 3. Resolve agent profile. ConfigError surfaces as a thrown error so the
-    // CLI dispatcher renders the standard envelope.
+    return createReflectProposal({
+        payload,
+        options,
+        stash,
+        engineName,
+        durationMs: result.durationMs,
+        emitReflectFailed,
+        outputTelemetry,
+    });
+}
+/**
+ * Create the reflect proposal from sanitized+judged payload: stamp the R-4/#373
+ * lesson provenance marker, call `createProposal`, and emit the terminal
+ * `reflect_completed` (or a cooldown skip envelope). Extracted verbatim from
+ * `akmReflect`'s finalize tail.
+ */
+function createReflectProposal(args) {
+    const { payload, options, stash, engineName, durationMs, emitReflectFailed, outputTelemetry } = args;
+    // 8. Create the proposal. The proposal queue is the ONLY thing reflect
+    // writes — promotion to a real asset is gated by `akm proposal accept`.
     //
-    // When an explicit --profile flag is given, honour it directly (existing
-    // behaviour). Otherwise use resolveProcessAgentProfile so that per-process
-    // agent config (agent.processes["reflect"]) is picked up automatically.
-    let profile;
-    let resolvedTimeoutMs = options.timeoutMs;
-    let runnerSpec;
-    try {
-        if (options.agentProfile) {
-            // Test seam: injected profile bypasses all config.
-            profile = options.agentProfile;
-        }
-        else if (options.runner) {
-            // Caller-provided RunnerSpec (used in tests and --dry-run-resolve).
-            runnerSpec = options.runner;
-        }
-        else {
-            const cfg = options.config ?? loadConfig();
-            const reflectProcess = getImproveProcessConfig(cfg, "reflect", options.improveProfile);
-            // Resolve the runner from the improve profile's reflect entry when present.
-            runnerSpec = resolveImproveProcessRunnerFromProfile(reflectProcess, cfg) ?? undefined;
-            if (runnerSpec) {
-                if (resolvedTimeoutMs === undefined && runnerSpec.timeoutMs !== undefined) {
-                    resolvedTimeoutMs = runnerSpec.timeoutMs;
-                }
-            }
-            else {
-                if (options.profile) {
-                    // Explicit --profile flag wins over process config.
-                    profile = resolveAgentProfile(options);
-                }
-                else {
-                    // Use per-process config resolution (falls back to defaults.agent).
-                    const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-                    const processName = options.agentProcess ?? "reflect";
-                    const resolved = resolveProcessAgentProfile(processName, agent);
-                    profile = resolved.profile;
-                    // Only apply process-resolved timeoutMs when caller didn't supply one.
-                    if (resolvedTimeoutMs === undefined) {
-                        resolvedTimeoutMs = resolved.timeoutMs;
-                    }
-                }
-            }
+    // R-4 / #373: Stamp `derived_from_reflect: true` in the frontmatter of any
+    // lesson proposal generated by reflect. This provenance marker lets
+    // `readRelatedLessons` exclude echo-chamber lessons (lessons that originate
+    // from prior reflect runs on the same skill) unless independent feedback
+    // evidence exists. ExpeL arXiv:2308.10144 — reject rules without success/
+    // failure differential from independent evidence.
+    const isLessonProposal = (() => {
+        try {
+            return parseRefInput(payload.ref).type === "lesson";
         }
-    }
-    catch (err) {
-        if (err instanceof ConfigError || err instanceof UsageError)
-            throw err;
-        throw err;
-    }
-    // P1.3 (meta-review 07, Chain G): unattended `akm improve` must never hand
-    // reflect a tool-capable runner. Agent-CLI/SDK runners have filesystem
-    // access, so a poisoned asset body flowing through the scheduled reflect
-    // prompt could steer an agent with tools; the tool-less LLM HTTP runner
-    // corrupts output text at worst (src/llm/call-ai.ts). An llm RunnerSpec
-    // resolved from the process block is honored; anything else — an agent/sdk
-    // spec, a resolved agent profile, or the default-agent fallback below — is
-    // pinned to `defaults.llm`, failing CLOSED when that is unset.
-    // `options.agentProfile` stays exempt: it is a direct-injection test seam
-    // the cron path (loop-stages) never sets.
-    if (options.eventSource === "improve" && !options.agentProfile && (!runnerSpec || !runnerIsLlm(runnerSpec))) {
-        const cfg = options.config ?? loadConfig();
-        const pinned = resolveDefaultLlmRunner(cfg, resolvedTimeoutMs);
-        if (!pinned) {
-            throw new ConfigError("Unattended improve pins reflect to the tool-less LLM runner, but the config resolves a tool-capable runner and no defaults.llm profile exists to pin to.", "LLM_NOT_CONFIGURED", 'Set processes.reflect.mode to "llm" on the active improve profile, or configure defaults.llm.');
+        catch {
+            return false;
         }
-        warn(runnerSpec
-            ? `[akm] reflect: unattended improve resolved a tool-capable "${runnerSpec.kind}" runner — pinned to the tool-less LLM runner (07 Chain-G).`
-            : "[akm] reflect: unattended improve would have fallen back to an agent profile — pinned to the tool-less LLM runner (07 Chain-G).");
-        runnerSpec = pinned;
-        profile = undefined;
-    }
-    // Ensure profile is set for agent/sdk runners that don't use runnerSpec
-    if (!runnerSpec && !profile) {
-        const agent = options.agentConfig ?? loadAgentConfigFromDisk();
-        profile = resolveAgentProfile({ ...options, agentConfig: agent });
-    }
-    // Derive a display name for logging — either from the resolved profile or the runnerSpec.
-    const resolvedProfileName = profile?.name ??
-        (runnerSpec && runnerIsLlm(runnerSpec)
-            ? `llm:${runnerSpec.connection.model}`
-            : runnerSpec
-                ? `${runnerSpec.kind}:${runnerSpec.profile.name ?? "unknown"}`
-                : "unknown");
-    // 4. Build the shared prompt inputs — feedback, hints, lessons, rejected
-    // proposals. These are stable across refinement iterations; only the
-    // `priorDraft` field changes per-iteration (R-1 / #372).
-    const feedback = readRecentFeedback(options.ref);
-    const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
-    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(stash, options.ref, parsedRef) : [];
-    // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
-    // reproducing proposals that have already been reviewed and refused.
-    const rejectedProposals = readRejectedProposals(stash, options.ref);
-    // Standards "rulebook" for this target — wiki schema (wiki page) or stash
-    // convention/meta facts (non-wiki asset); empty when neither fires.
-    const standardsContext = resolveStandardsContext(options.ref, stash);
-    // 5. Spawn the agent — with optional Self-Refine loop (R-1 / #372).
-    //
-    // maxRefineIters controls how many agent invocations are made:
-    //   - 1 (default): single-shot, same as pre-R-1 behaviour
-    //   - 2–3: on each subsequent pass, the prior draft is injected back into
-    //     the prompt as Self-Refine critique context (arXiv:2303.17651)
-    //
-    // The loop exits early when the agent returns the same content as before
-    // (no-op refinement) to avoid wasting tokens on identical iterations.
-    const MAX_REFINE_ITERS = 3;
-    const maxRefineIters = Math.min(Math.max(1, options.maxRefineIters ?? 1), MAX_REFINE_ITERS);
-    const agentEnv = options.eventSource === "improve" ? { AKM_EVENT_SOURCE: "improve" } : {};
+    })();
+    const basePayloadFrontmatter = payload.frontmatter ?? {};
+    const payloadFrontmatterWithProvenance = isLessonProposal
+        ? { ...basePayloadFrontmatter, derived_from_reflect: true }
+        : basePayloadFrontmatter;
+    const createInput = {
+        ref: payload.ref,
+        ...(options.target ? { target: options.target } : {}),
+        source: "reflect",
+        sourceRun: `reflect-${Date.now()}`,
+        payload: {
+            content: payload.content,
+            ...(Object.keys(payloadFrontmatterWithProvenance).length > 0
+                ? { frontmatter: payloadFrontmatterWithProvenance }
+                : {}),
+        },
+        // Phase 6A: forward LLM-reported confidence into the proposal record.
+        // `parseAgentProposalPayload` already clamps to [0, 1] and drops non-
+        // finite values; `createProposal` runs its own sanitizer as a safety net.
+        ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal so it
+        // survives to accept/reject/revert time even across runs. See EligibilitySource.
+        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
+        // §23.6 fingerprint model-id term (WI-6.4): the engine that generated
+        // this draft (reflect resolves engines, not bare model ids).
+        modelId: engineName,
+    };
+    const proposalResult = emitProposal({ stashDir: stash, proposalsCtx: options.ctx }, createInput);
+    if (isProposalSkipped(proposalResult)) {
+        // Dedup/cooldown guard fired — surface as a "cooldown" reason (not "parse_error")
+        // so the improve orchestrator can distinguish legitimate skips from real failures
+        // and exclude them from recentErrors/avoidPatterns injection.
+        emitReflectFailed("cooldown", "proposal_skipped", options.ref, {
+            proposalSkipReason: proposalResult.reason,
+            ...(outputTelemetry ?? {}),
+        });
+        return {
+            schemaVersion: 2,
+            ok: false,
+            reason: "cooldown",
+            error: `Proposal skipped (${proposalResult.reason}): ${proposalResult.message}`,
+            ...(options.ref ? { ref: options.ref } : {}),
+            engine: engineName,
+            exitCode: null,
+        };
+    }
+    const proposal = proposalResult;
+    appendEvent({
+        eventType: "reflect_completed",
+        ref: proposal.ref,
+        metadata: {
+            proposalId: proposal.id,
+            source: "reflect",
+            engine: engineName,
+            ...(outputTelemetry ?? {}),
+        },
+    }, options.eventsCtx);
+    return {
+        schemaVersion: 2,
+        ok: true,
+        proposal,
+        ref: proposal.ref,
+        engine: engineName,
+        durationMs,
+    };
+}
+/**
+ * Resolve the agent's proposal payload from a successful run: the file-write
+ * contract path (read `lastDraftPath`, extract self-rated confidence) or the
+ * JSON-stdout path used by direct LLM runners. Returns the payload or a terminal
+ * failure envelope.
+ */
+function resolveReflectPayload(args) {
+    const { result, lastDraftPath, sensitiveValues, options, engineName, emitReflectFailed } = args;
+    // 6. Resolve the proposal content.
+    //
+    // Path A (file-write contract — preferred for agent/sdk runners on long
+    // assets): the agent wrote the body to `lastDraftPath` and printed
+    // `DRAFT_WRITTEN` on stdout. Load the body from disk and synthesize a
+    // payload. The `EXCESSIVE_EXPANSION`/schema-shape gates downstream still
+    // apply — they validate content, not transport.
+    //
+    // Path B (JSON stdout): the direct LLM runner cannot honour file-write.
+    const draftFileExists = lastDraftPath !== undefined && fs.existsSync(lastDraftPath) && fs.statSync(lastDraftPath).size > 0;
+    const draftSignaled = stdoutSignalsDraftWritten(result.stdout);
+    if (draftSignaled && lastDraftPath && !draftFileExists) {
+        // Agent claimed to write the draft but the file is missing or empty.
+        // Surface as a parse_error rather than silently falling through — the
+        // alternative would be parsing the `DRAFT_WRITTEN` sentinel as JSON,
+        // which is guaranteed to fail with a confusing message.
+        emitReflectFailed("parse_error", "draft_missing", options.ref, {
+            ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        });
+        return {
+            failure: {
+                schemaVersion: 2,
+                ok: false,
+                reason: "parse_error",
+                error: `Agent emitted DRAFT_WRITTEN but draft file is missing or empty (${lastDraftPath}). The file-write contract failed; either the agent's file tools are broken or the path was unwritable.`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                engine: engineName,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            },
+        };
+    }
+    if (draftFileExists && lastDraftPath) {
+        // Happy path: agent wrote the body to disk. Use the ref the caller
+        // supplied (or a placeholder when omitted — the R-3 ref-mismatch guard
+        // below has no effect when there is no expected ref).
+        const fileContent = redactSensitiveText(fs.readFileSync(lastDraftPath, "utf8"), sensitiveValues);
+        // Phase 6A: file-write contract carries self-rated confidence on the
+        // `DRAFT_WRITTEN confidence=<n>` sentinel line. Extract it so the
+        // file-write path is on equal footing with the JSON-stdout path for
+        // auto-accept gating in `akm improve`.
+        const draftConfidence = extractDraftConfidence(result.stdout);
+        return {
+            payload: {
+                ref: options.ref ?? "",
+                content: fileContent,
+                ...(draftConfidence !== undefined ? { confidence: draftConfidence } : {}),
+            },
+        };
+    }
+    try {
+        return { payload: parseAgentProposalPayload(result.stdout ?? "") };
+    }
+    catch (err) {
+        // Reclassify cooldown/skip messages that arrive as stdout text instead of
+        // valid proposal JSON. These are legitimate skip signals, not parse failures,
+        // and should not pollute reflectFailedActions or recentErrors injection.
+        const stdoutText = result.stdout ?? "";
+        const isCooldownSignal = isStructuredCooldownSignal(stdoutText);
+        const reason = isCooldownSignal ? "cooldown" : "parse_error";
+        emitReflectFailed(reason, isCooldownSignal ? "stdout_cooldown_signal" : "parse_error", options.ref, {
+            ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+            ...(reflectLlmTelemetry(result) ?? {}),
+        });
+        return {
+            failure: {
+                schemaVersion: 2,
+                ok: false,
+                reason,
+                error: err instanceof Error ? err.message : String(err),
+                ...(options.ref ? { ref: options.ref } : {}),
+                engine: engineName,
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                ...(result.stderr ? { stderr: result.stderr } : {}),
+            },
+        };
+    }
+}
+/**
+ * Resolve the single named engine for a reflect invocation (standalone --engine
+ * / defaults.engine, or the improve strategy's LLM-only process overlay),
+ * throwing on any incompatible or missing engine, and validating the unattended
+ * LLM requirement. Extracted verbatim from `akmReflect`.
+ */
+function resolveReflectRunner(options) {
+    const config = options.config ?? loadConfig();
+    const activeStrategy = options.improveProfile ?? config.improve?.strategies?.[config.defaults?.improveStrategy ?? "default"];
+    let runnerSpec;
+    if (options.runner) {
+        runnerSpec = options.runner;
+    }
+    else if (Object.hasOwn(options, "runner")) {
+        throw new ConfigError("Reflect requires an LLM engine for the active improve invocation.", "LLM_NOT_CONFIGURED", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine.");
+    }
+    else if (options.engine) {
+        runnerSpec = resolveEngine(options.engine, config);
+    }
+    else if (options.improveProfile) {
+        const processRunner = resolveImproveProcessRunner(activeStrategy, "reflect", config);
+        if (!processRunner) {
+            throw new ConfigError("Reflect requires an LLM engine for the active improve strategy.", "LLM_NOT_CONFIGURED", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine.");
+        }
+        runnerSpec = processRunner;
+    }
+    else {
+        const defaultEngine = config.defaults?.engine;
+        if (!defaultEngine) {
+            throw new ConfigError("reflect requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
+        }
+        runnerSpec = resolveEngine(defaultEngine, config);
+    }
+    if (options.eventSource === "improve" && !runnerIsLlm(runnerSpec)) {
+        throw new ConfigError(`Unattended improve requires an LLM engine for reflect; engine "${runnerSpec.engine ?? options.engine ?? "unknown"}" is tool-capable.`, "INVALID_CONFIG_FILE", "Set defaults.llmEngine or improve.strategies.<name>.processes.reflect.engine to an LLM engine.");
+    }
+    const engineName = runnerSpec.engine ?? options.engine;
+    if (!engineName) {
+        throw new ConfigError("Reflect requires a named engine.", "INVALID_CONFIG_FILE");
+    }
+    return { config, activeStrategy, runnerSpec, engineName };
+}
+/**
+ * Resolve the reflect target's parsed ref + current on-disk content: enforce the
+ * REFLECT_ALLOWED_TYPES markdown-canonical type guard (returning a terminal
+ * `unsupported_type` failure), honour the `options.assetContent` test seam, else
+ * best-effort load via the local file path / index lookup. Extracted verbatim
+ * from `akmReflect`.
+ */
+async function resolveReflectSource(options, stash, emitReflectFailed) {
+    let assetContent;
+    let parsedRef;
+    if (options.ref) {
+        parsedRef = parseRefInput(options.ref);
+        // 2a. Type guard — reflect only operates on asset types whose canonical
+        // shape is `frontmatter + markdown body`. Refuse non-markdown types
+        // (script / env / task) up-front so reflect never prepends YAML to a
+        // `.ts` file or rewrites a `.env` blob as prose. See REFLECT_ALLOWED_TYPES.
+        if (!REFLECT_ALLOWED_TYPES.has(parsedRef.type)) {
+            // Deterministic type-guard rejection — the LLM is never invoked. Emit
+            // with reason `unsupported_type` so the improve loop can route this to
+            // the `reflect-skipped` action bucket instead of `reflect-failed`. See
+            // `/tmp/akm-health-investigations/metrics-taxonomy-review.md` §1a
+            // ("Reflect refused asset type" — ~9% of reflect-failed events).
+            emitReflectFailed("unsupported_type", "unsupported_type", options.ref, { type: parsedRef.type });
+            return {
+                failure: {
+                    schemaVersion: 2,
+                    ok: false,
+                    reason: "unsupported_type",
+                    error: `Reflect refused: asset type "${parsedRef.type}" is not supported by reflect (only markdown-canonical types are allowed: ${[...REFLECT_ALLOWED_TYPES].sort().join(", ")}). Use \`akm proposal new\` or edit the file directly.`,
+                    ref: options.ref,
+                    exitCode: null,
+                },
+            };
+        }
+        if (options.assetContent !== undefined) {
+            // Test seam — caller pre-loaded the source content.
+            assetContent = options.assetContent;
+        }
+        else {
+            try {
+                // Resolve the source by item_ref when planning supplied one, otherwise
+                // use the input conceptId.
+                const qualifiedRef = options.itemRef ?? durableImproveRef(options.ref);
+                const localFilePath = await findAssetFilePath(qualifiedRef, stash);
+                if (localFilePath && fs.existsSync(localFilePath)) {
+                    assetContent = fs.readFileSync(localFilePath, "utf8");
+                }
+                else {
+                    const entry = await lookup(parseRefInput(qualifiedRef));
+                    if (entry?.filePath && fs.existsSync(entry.filePath)) {
+                        assetContent = fs.readFileSync(entry.filePath, "utf8");
+                    }
+                }
+            }
+            catch {
+                // Index miss is non-fatal — the agent can still propose a fresh asset.
+            }
+        }
+    }
+    return { assetContent, parsedRef };
+}
+/**
+ * Run the agent with the optional Self-Refine loop (R-1 / #372): up to
+ * MAX_REFINE_ITERS invocations, each injecting the prior draft as self-critique
+ * context and exiting early on a no-op refinement. Synthesizes per-iteration
+ * draft paths into `draftPathsToCleanup` (mutated) and returns the final agent
+ * result + last draft path. Extracted verbatim from `akmReflect`.
+ */
+async function runReflectRefineIterations(args) {
+    const { options, parsedRef, assetContent, feedback, schemaHints, relatedLessons, rejectedProposals, standardsContext, runnerSpec, agentEnv, draftPathsToCleanup, } = args;
+    const MAX_REFINE_ITERS = 3;
+    const maxRefineIters = Math.min(Math.max(1, options.maxRefineIters ?? 1), MAX_REFINE_ITERS);
     // Determine whether this dispatch can honour the file-write contract.
     // Agent CLI + OpenCode SDK runners both have filesystem access; the direct
-    // LLM HTTP runner does NOT (see `src/llm/call-ai.ts:64-71`). The v1
-    // `profile.sdkMode` fallback also runs the SDK so it counts as file-writable.
-    // Test seams (`options.runAgentOptions.spawn`) emulate agent CLI behaviour so
-    // they participate as well — tests opt out by simply not writing the file.
-    const canRunnerWriteFile = runnerSpec ? runnerSupportsFileWrite(runnerSpec) : true;
+    // LLM HTTP runner does NOT.
+    const canRunnerWriteFile = runnerSupportsFileWrite(runnerSpec);
+    const outputMode = runnerIsLlm(runnerSpec)
+        ? runnerSpec.connection.supportsJsonSchema
+            ? "json_schema"
+            : "framed_markdown"
+        : undefined;
     // Initialized to a sentinel; always overwritten in the first loop iteration
-    // (maxRefineIters is clamped to >= 1 above). TypeScript cannot prove a
-    // for-loop always runs at least once, so we use a type assertion here.
+    // (maxRefineIters is clamped to >= 1 above).
     let result = {};
     let priorDraft;
+    let lastDraftPath;
+    let repairAttempts = 0;
+    for (let iter = 0; iter < maxRefineIters; iter++) {
+        // Synthesize a fresh tmp path per iteration so refinement passes never
+        // clobber an earlier draft (and so reading back is unambiguous).
+        const iterDraftPath = canRunnerWriteFile ? synthesizeReflectDraftPath(options.ref) : undefined;
+        if (iterDraftPath) {
+            draftPathsToCleanup.push(iterDraftPath);
+            lastDraftPath = iterDraftPath;
+        }
+        const { prompt, maxOutputChars } = buildReflectPrompt({
+            ...(options.ref ? { ref: options.ref } : {}),
+            ...(parsedRef?.type ? { type: parsedRef.type } : {}),
+            ...(parsedRef?.name ? { name: parsedRef.name } : {}),
+            ...(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 } : {}),
+            ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
+            // R-1: inject prior draft as self-critique target on iterations > 0
+            ...(priorDraft !== undefined ? { priorDraft } : {}),
+            // Issue A (#reflect-pipeline file-write contract): when the runner can
+            // touch the filesystem, instruct the agent to write the proposal body
+            // to a tmp file instead of inlining it in JSON. Avoids parse failures
+            // on long bodies (e.g. knowledge/systems/KOKORO_USAGE_GUIDE 8.4KB).
+            ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
+            ...(outputMode ? { outputMode } : {}),
+        });
+        // Convert char ceiling → token cap for the LLM path: divide by 3 chars/token
+        // (conservative — most models are 3.5–4) and add 500-char overhead for the
+        // JSON wrapper and frontmatter block that surround the body in the response.
+        const maxTokensForLlm = maxOutputChars !== undefined ? Math.ceil((maxOutputChars + 500) / 3) : undefined;
+        // Every engine kind crosses the same dispatch seam. Injected spawn/timer
+        // functions remain ordinary run options for deterministic tests.
+        const runOptions = {
+            stdio: "captured",
+            parseOutput: "text",
+            ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+            ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
+            ...(options.runAgentOptions ?? {}),
+        };
+        const iterResult = await executeRunner(runnerSpec, prompt ?? "", runOptions, {
+            llm: async (spec, _prompt, opts) => 
+            // LLM HTTP runners cannot honor the file-write contract, so they
+            // return structured JSON through stdout.
+            runReflectViaLlm({
+                prompt,
+                connection: spec.connection,
+                ...(Object.hasOwn(opts, "timeoutMs") ? { timeoutMs: opts.timeoutMs } : {}),
+                ...(options.signal ? { signal: options.signal } : {}),
+                priorDraft,
+                iteration: iter,
+                ...(spec.connection.supportsJsonSchema
+                    ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
+                    : {}),
+                outputMode: spec.connection.supportsJsonSchema ? "json_schema" : "framed_markdown",
+                ...(options.ref ? { targetRef: options.ref } : {}),
+                allowRepair: repairAttempts === 0,
+                chat: options.chat,
+                ...(maxTokensForLlm !== undefined ? { maxTokens: maxTokensForLlm } : {}),
+            }),
+        });
+        const iterTelemetry = reflectLlmTelemetry(iterResult);
+        if (iterTelemetry)
+            repairAttempts += iterTelemetry.repairAttempts;
+        result = iterTelemetry
+            ? {
+                ...iterResult,
+                parsed: {
+                    ...iterResult.parsed,
+                    ...iterTelemetry,
+                    repairAttempts,
+                },
+            }
+            : iterResult;
+        if (!result.ok)
+            break; // surface failure after loop
+        // On success, extract the draft content for the next iteration.
+        // If the agent returns the same content as the prior draft, stop early
+        // (no-op refinement) to avoid wasting tokens on identical iterations.
+        if (iter < maxRefineIters - 1) {
+            const nextDraft = reflectLlmPriorDraft(result) ?? result.stdout ?? "";
+            if (priorDraft !== undefined && nextDraft === priorDraft)
+                break;
+            priorDraft = nextDraft;
+        }
+    }
+    return { result, lastDraftPath };
+}
+/**
+ * WI-9.10: build one `akm reflect` invocation's {@link RunContext} purely
+ * from values `akmReflect` has already resolved by the time it calls this
+ * (stash, config, runnerSpec) plus the caller-supplied seams on `options` —
+ * no second config load, no new db handle. reflect has no `dryRun` option
+ * (it never writes source assets directly, only the proposal queue — see the
+ * module docblock) so `dryRun` is always `false` here. reflect also has no
+ * `sourceRun` option; the value below mirrors the same `reflect-${Date.now()}`
+ * convention already used inline at proposal creation time (see
+ * `createInput` further down this file), as a fresh, independent token —
+ * nothing yet reads `ctx.sourceRun`.
+ */
+function buildReflectRunContext(args) {
+    const { options, stash, config, runnerSpec } = args;
+    return createRunContext({
+        stashDir: stash,
+        config,
+        eventsCtx: options.eventsCtx ?? {},
+        // Not yet wired into any proposal call site this stage (mirrors
+        // buildImproveRunContext's proposalsCtx comment in improve.ts).
+        proposalsCtx: options.ctx ?? {},
+        chat: options.chat,
+        getLlmConfig: () => (runnerIsLlm(runnerSpec) ? materializeLlmRunnerConnection(runnerSpec) : null),
+        sourceRun: `reflect-${Date.now()}`,
+        dryRun: false,
+        signal: options.signal,
+    });
+}
+/**
+ * Emit `reflect_invoked` at command entry, then build the `reflect_completed`
+ * failure emitter every failure path in `akmReflect` uses (Fix #3 /
+ * observability 0.8.0). Extracted verbatim (fn-size decomposition, R31) — see
+ * the original inline comments preserved below for the "why".
+ *
+ * Fix #3 (observability 0.8.0): every failure path below MUST emit
+ * `reflect_completed` so observers can close the invoke/complete loop. The
+ * three success-side `reflect_completed` emit sites carry rich metadata
+ * (qualityRejected, sanitized, proposalId, etc.); the failure-side emits
+ * carry `{ok: false, reason}` plus the ref when known. Stable failure
+ * reasons line up with `AgentFailureReason`: "parse_error", "non_zero_exit",
+ * "cooldown", "timeout", "spawn_failed", "llm_*", plus the synthetic
+ * "ref_mismatch" / "enoent" / "draft_missing" subtypes for cases the agent
+ * surface conflates as "parse_error". Sub-reasons land in `subreason`.
+ */
+function emitReflectInvokedAndBuildFailureEmitter(options) {
+    // Always emit `reflect_invoked` at command entry — observers see the
+    // attempt regardless of downstream success/failure.
+    appendEvent({
+        eventType: "reflect_invoked",
+        // Key on item_ref when planning supplied one, otherwise the conceptId.
+        ...(options.ref ? { ref: options.itemRef ?? durableImproveRef(options.ref) } : {}),
+        metadata: {
+            ...(options.task ? { task: options.task } : {}),
+            ...(options.engine ? { engine: options.engine } : {}),
+            // Attribution tagging: stamp the eligibility lane so reflect_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
+        },
+    }, options.eventsCtx);
+    return (reason, subreason, ref, extra) => {
+        appendEvent({
+            eventType: "reflect_completed",
+            ...(ref ? { ref } : {}),
+            metadata: {
+                source: "reflect",
+                ok: false,
+                reason,
+                subreason,
+                ...(extra ?? {}),
+            },
+        }, options.eventsCtx);
+    };
+}
+export async function akmReflect(options = {}) {
+    const stash = resolveRunStashDir(options.stashDir);
+    // 1. Emit reflect_invoked + build the reflect_completed failure emitter
+    // every failure path below uses.
+    const emitReflectFailed = emitReflectInvokedAndBuildFailureEmitter(options);
+    // 2. Resolve target asset content (if a ref is supplied).
+    const sourceResolved = await resolveReflectSource(options, stash, emitReflectFailed);
+    if ("failure" in sourceResolved)
+        return sourceResolved.failure;
+    const { assetContent, parsedRef } = sourceResolved;
+    // 3. Resolve exactly one named engine. Standalone reflect uses --engine or
+    // defaults.engine; improve resolves its LLM-only strategy/process overlay.
+    // An incompatible explicit engine is an error and never falls through.
+    const { config, activeStrategy, runnerSpec, engineName } = resolveReflectRunner(options);
+    // WI-9.10: RunContext, built only once config/runnerSpec exist so engine
+    // resolution's existing error-priority ordering is undisturbed (see
+    // buildReflectRunContext's docblock). D6: assetCtx is a fresh,
+    // per-invocation memo — readRelatedLessons below is its genuine
+    // content-read consumer.
+    const ctx = buildReflectRunContext({ options, stash, config, runnerSpec });
+    const assetCtx = ctx.withFreshAssetMemo();
+    // 4. Build the shared prompt inputs — feedback, hints, lessons, rejected
+    // proposals. These are stable across refinement iterations; only the
+    // `priorDraft` field changes per-iteration (R-1 / #372).
+    const feedback = readRecentFeedback(options.ref ? (options.itemRef ?? durableImproveRef(options.ref)) : undefined);
+    const schemaHints = buildSchemaHints(parsedRef?.type ?? "", assetContent);
+    const relatedLessons = options.ref && parsedRef ? await readRelatedLessons(assetCtx, stash, options.ref, parsedRef, options.itemRef) : [];
+    // Reflexion-style verbal-RL: inject rejected proposals so the agent avoids
+    // reproducing proposals that have already been reviewed and refused.
+    const rejectedProposals = readRejectedProposals(stash, options.ref);
+    // Standards "rulebook" for this target — stash convention/meta facts; empty
+    // when none fire.
+    const standardsContext = resolveStandardsContext(options.ref, stash);
+    // 5. Spawn the agent — with the optional Self-Refine loop (R-1 / #372),
+    // extracted to {@link runReflectRefineIterations}.
+    const agentEnv = options.eventSource === "improve" ? { AKM_EVENT_SOURCE: "improve" } : {};
+    const sensitiveValues = collectDispatchSensitiveValues(runnerSpec, {
+        ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
+        ...(options.runAgentOptions ?? {}),
+    });
     // Track every draft file path we synthesize so cleanup can remove them on
     // every return path (success and failure). Mirrors propose's unlink pattern
-    // in `src/commands/propose.ts:215-226` but generalised to N refinement
+    // in `src/commands/proposal/propose.ts` but generalised to N refinement
     // iterations. Always called via {@link cleanupDrafts} below.
     const draftPathsToCleanup = [];
-    // Last iteration's draft path — read back if the agent wrote it.
-    let lastDraftPath;
     // Best-effort unlink: tolerate already-deleted files (we may have unlinked
     // an intermediate iteration's draft) and unwritable paths. Never throws —
     // the proposal result is the source of truth for the caller.
@@ -922,127 +1509,28 @@ export async function akmReflect(options = {}) {
             }
         }
     };
-    // `payload` is populated inside the try (either by reading the draft file
-    // or parsing stdout JSON). Hoisted here so the post-try sections (R-3 ref
-    // guard, quality gate, sanitizer, createProposal) can use it after the
-    // drafts have been cleaned up.
+    // `result` / `lastDraftPath` / `payload` are populated inside the try. Hoisted
+    // here so the post-try sections (R-3 ref guard, sanitizer, quality gate,
+    // createProposal) can use them after the drafts have been cleaned up.
+    let result = {};
+    let lastDraftPath;
     let payload;
     try {
-        for (let iter = 0; iter < maxRefineIters; iter++) {
-            // Synthesize a fresh tmp path per iteration so refinement passes never
-            // clobber an earlier draft (and so reading back is unambiguous).
-            const iterDraftPath = canRunnerWriteFile ? synthesizeReflectDraftPath(options.ref) : undefined;
-            if (iterDraftPath) {
-                draftPathsToCleanup.push(iterDraftPath);
-                lastDraftPath = iterDraftPath;
-            }
-            const { prompt, maxOutputChars } = buildReflectPrompt({
-                ...(options.ref ? { ref: options.ref } : {}),
-                ...(parsedRef?.type ? { type: parsedRef.type } : {}),
-                ...(parsedRef?.name ? { name: parsedRef.name } : {}),
-                ...(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 } : {}),
-                ...(rejectedProposals.length > 0 ? { rejectedProposals } : {}),
-                // R-1: inject prior draft as self-critique target on iterations > 0
-                ...(priorDraft !== undefined ? { priorDraft } : {}),
-                // Issue A (#reflect-pipeline file-write contract): when the runner can
-                // touch the filesystem, instruct the agent to write the proposal body
-                // to a tmp file instead of inlining it in JSON. Avoids parse failures
-                // on long bodies (e.g. knowledge:systems/KOKORO_USAGE_GUIDE 8.4KB).
-                ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
-            });
-            // Convert char ceiling → token cap for the LLM path: divide by 3 chars/token
-            // (conservative — most models are 3.5–4) and add 500-char overhead for the
-            // JSON wrapper and frontmatter block that surround the body in the response.
-            const maxTokensForLlm = maxOutputChars !== undefined ? Math.ceil((maxOutputChars + 500) / 3) : undefined;
-            let iterResult;
-            if (options.runAgentOptions?.spawn) {
-                // Test seam: use raw runAgent with injected spawn so tests remain deterministic.
-                const resolvedProfile = profile;
-                if (!resolvedProfile) {
-                    throw new Error("internal: reflect test-seam path requires a resolved agent profile");
-                }
-                const runOptions = {
-                    stdio: "captured",
-                    parseOutput: "text",
-                    ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
-                    ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
-                    ...(options.runAgentOptions ?? {}),
-                };
-                iterResult = await runAgent(resolvedProfile, prompt, runOptions);
-            }
-            else if (runnerSpec) {
-                // v2: dispatch through the unified RunnerSpec seam (X3). The `agent` /
-                // `sdk` arms route to the default profile runners; the `llm` arm is
-                // reflect-specific (wraps `runReflectViaLlm` — its bespoke iteration
-                // shape) so it is supplied as the `llm` handler.
-                const runOptions = {
-                    stdio: "captured",
-                    parseOutput: "text",
-                    ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
-                };
-                iterResult = await executeRunner(runnerSpec, prompt ?? "", runOptions, {
-                    llm: async (spec) => 
-                    // LLM HTTP path — `draftFilePath` is accepted for type symmetry
-                    // (see `RunReflectViaLlmOptions.draftFilePath` docstring) but is
-                    // intentionally a no-op. The prompt builder above also did not
-                    // include the file-write contract for this kind, so the LLM is
-                    // still asked for JSON via stdout.
-                    runReflectViaLlm({
-                        prompt,
-                        connection: spec.connection,
-                        timeoutMs: spec.timeoutMs ?? (typeof resolvedTimeoutMs === "number" ? resolvedTimeoutMs : undefined),
-                        priorDraft,
-                        iteration: iter,
-                        responseSchema: REFLECT_JSON_SCHEMA,
-                        chat: options.chat,
-                        ...(maxTokensForLlm !== undefined ? { maxTokens: maxTokensForLlm } : {}),
-                    }),
-                    // The `agent` arm (and only the agent arm — preserving prior behavior)
-                    // overlays `spec.timeoutMs` onto the base run options.
-                    runAgent: (profile, p, opts) => runAgent(profile, p, {
-                        ...opts,
-                        ...(runnerSpec.timeoutMs !== undefined ? { timeoutMs: runnerSpec.timeoutMs } : {}),
-                    }),
-                });
-            }
-            else {
-                // Production path (v1): dispatch directly to the appropriate runner.
-                // The fallback at the end of step 3 guarantees `profile` is set whenever
-                // `runnerSpec` is undefined, but TS can't prove that across the loop +
-                // await boundary — narrow into a const.
-                const resolvedProfile = profile;
-                if (!resolvedProfile) {
-                    throw new Error("internal: reflect v1 dispatch reached without a resolved agent profile or runnerSpec");
-                }
-                const runOptions = {
-                    stdio: "captured",
-                    parseOutput: "text",
-                    ...(resolvedTimeoutMs !== undefined ? { timeoutMs: resolvedTimeoutMs } : {}),
-                    ...(Object.keys(agentEnv).length > 0 ? { env: agentEnv } : {}),
-                };
-                iterResult = resolvedProfile.sdkMode
-                    ? await runOpencodeSdk(resolvedProfile, prompt ?? "", runOptions)
-                    : await runAgent(resolvedProfile, prompt, runOptions);
-            }
-            result = iterResult;
-            if (!iterResult.ok)
-                break; // surface failure after loop
-            // On success, extract the draft content for the next iteration.
-            // If the agent returns the same content as the prior draft, stop early
-            // (no-op refinement) to avoid wasting tokens on identical iterations.
-            if (iter < maxRefineIters - 1) {
-                const nextDraft = iterResult.stdout ?? "";
-                if (priorDraft !== undefined && nextDraft === priorDraft)
-                    break;
-                priorDraft = nextDraft;
-            }
-        }
+        const iterated = await runReflectRefineIterations({
+            options,
+            parsedRef,
+            assetContent,
+            feedback,
+            schemaHints,
+            relatedLessons,
+            rejectedProposals,
+            standardsContext,
+            runnerSpec,
+            agentEnv,
+            draftPathsToCleanup,
+        });
+        result = iterated.result;
+        lastDraftPath = iterated.lastDraftPath;
         const finalResult = result;
         if (!finalResult.ok) {
             // B3: ENOENT / not-found gives an actionable hint.
@@ -1051,102 +1539,30 @@ export async function akmReflect(options = {}) {
                     ...(finalResult.exitCode !== undefined ? { exitCode: finalResult.exitCode } : {}),
                 });
                 return {
-                    ...failureEnvelope(finalResult, options.ref),
-                    error: enoentHintMessage(profile?.bin ?? resolvedProfileName),
+                    ...failureEnvelope(finalResult, options.ref, engineName),
+                    error: enoentHintMessage(runnerIsLlm(runnerSpec) ? engineName : runnerSpec.profile.bin),
                 };
             }
-            const envelope = failureEnvelope(finalResult, options.ref);
-            emitReflectFailed(envelope.reason, "agent_crash", options.ref, {
+            const envelope = failureEnvelope(finalResult, options.ref, engineName);
+            emitReflectFailed(envelope.reason, envelope.reason === "parse_error" ? "parse_error" : "agent_crash", options.ref, {
                 ...(envelope.exitCode !== null ? { exitCode: envelope.exitCode } : {}),
+                ...(reflectLlmTelemetry(finalResult) ?? {}),
             });
             return envelope;
         }
         // Re-alias to `result` for the downstream code that references it.
         result = finalResult;
-        // 6. Resolve the proposal content.
-        //
-        // Path A (file-write contract — preferred for agent/sdk runners on long
-        // assets): the agent wrote the body to `lastDraftPath` and printed
-        // `DRAFT_WRITTEN` on stdout. Load the body from disk and synthesize a
-        // payload. The `EXCESSIVE_EXPANSION`/schema-shape gates downstream still
-        // apply — they validate content, not transport.
-        //
-        // Path B (legacy JSON stdout): the agent inlined the proposal body in
-        // JSON on stdout. Falls through to `parseAgentProposalPayload`. Also the
-        // path used by the LLM HTTP runner, which cannot honour file-write.
-        const draftFileExists = lastDraftPath !== undefined && fs.existsSync(lastDraftPath) && fs.statSync(lastDraftPath).size > 0;
-        const draftSignaled = stdoutSignalsDraftWritten(result.stdout);
-        if (draftSignaled && lastDraftPath && !draftFileExists) {
-            // Agent claimed to write the draft but the file is missing or empty.
-            // Surface as a parse_error rather than silently falling through — the
-            // alternative would be parsing the `DRAFT_WRITTEN` sentinel as JSON,
-            // which is guaranteed to fail with a confusing message.
-            emitReflectFailed("parse_error", "draft_missing", options.ref, {
-                ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
-            });
-            return {
-                schemaVersion: 1,
-                ok: false,
-                reason: "parse_error",
-                error: `Agent emitted DRAFT_WRITTEN but draft file is missing or empty (${lastDraftPath}). The file-write contract failed; either the agent's file tools are broken or the path was unwritable.`,
-                ...(options.ref ? { ref: options.ref } : {}),
-                exitCode: result.exitCode,
-                stdout: result.stdout,
-                ...(result.stderr ? { stderr: result.stderr } : {}),
-            };
-        }
-        if (draftFileExists && lastDraftPath) {
-            // Happy path: agent wrote the body to disk. Use the ref the caller
-            // supplied (or a placeholder when omitted — the R-3 ref-mismatch guard
-            // below has no effect when there is no expected ref).
-            const fileContent = fs.readFileSync(lastDraftPath, "utf8");
-            // Phase 6A: file-write contract carries self-rated confidence on the
-            // `DRAFT_WRITTEN confidence=<n>` sentinel line. Extract it so the
-            // file-write path is on equal footing with the JSON-stdout path for
-            // auto-accept gating in `akm improve`.
-            const draftConfidence = extractDraftConfidence(result.stdout);
-            payload = {
-                ref: options.ref ?? "",
-                content: fileContent,
-                ...(draftConfidence !== undefined ? { confidence: draftConfidence } : {}),
-            };
-            // The agent followed the file-write contract — `payload.ref` mirrors the
-            // caller's expected ref, so the R-3 guard below cannot fire. The agent
-            // had no opportunity to retarget the proposal. If the ref was omitted
-            // entirely, downstream `createProposal` will reject the empty ref.
-        }
-        else {
-            try {
-                payload = parseAgentProposalPayload(result.stdout ?? "");
-            }
-            catch (err) {
-                const fallback = fallbackPayloadFromRawContent(result.stdout ?? "", options.ref, profile?.sdkMode ?? false);
-                if (fallback) {
-                    payload = fallback;
-                }
-                else {
-                    // Reclassify cooldown/skip messages that arrive as stdout text instead of
-                    // valid proposal JSON. These are legitimate skip signals, not parse failures,
-                    // and should not pollute reflectFailedActions or recentErrors injection.
-                    const stdoutText = result.stdout ?? "";
-                    const isCooldownSignal = isStructuredCooldownSignal(stdoutText);
-                    const reason = isCooldownSignal ? "cooldown" : "parse_error";
-                    emitReflectFailed(reason, isCooldownSignal ? "stdout_cooldown_signal" : "parse_error", options.ref, {
-                        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
-                    });
-                    return {
-                        schemaVersion: 1,
-                        ok: false,
-                        reason,
-                        error: err instanceof Error ? err.message : String(err),
-                        ...(options.ref ? { ref: options.ref } : {}),
-                        exitCode: result.exitCode,
-                        stdout: result.stdout,
-                        ...(result.stderr ? { stderr: result.stderr } : {}),
-                    };
-                }
-            }
-        }
+        const resolved = resolveReflectPayload({
+            result,
+            lastDraftPath,
+            sensitiveValues,
+            options,
+            engineName,
+            emitReflectFailed,
+        });
+        if ("failure" in resolved)
+            return resolved.failure;
+        payload = resolved.payload;
     }
     finally {
         // Always remove tmp draft files — success, failure, or exception. Returns
@@ -1155,28 +1571,31 @@ export async function akmReflect(options = {}) {
         // draft paths.
         cleanupDrafts();
     }
+    payload = { ...payload, content: redactSensitiveText(payload.content, sensitiveValues) };
     // 6b. Validate payload.ref === options.ref (R-3 / #366).
     // A hallucinating agent can silently retarget proposals to a different ref.
-    // This guard normalises both refs through parseAssetRef so origin-prefix
-    // differences do not cause false positives, then rejects mismatches.
+    // Parse both current refs so an optional bundle prefix does not cause a false
+    // positive, then reject genuine concept mismatches.
     // References: CRITIC (arXiv:2305.11738), CoVe (arXiv:2309.11495).
     if (options.ref) {
         try {
-            const expectedParsed = parseAssetRef(options.ref);
-            const actualParsed = parseAssetRef(payload.ref);
+            const expectedParsed = parseRefInput(options.ref);
+            const actualParsed = parseRefInput(payload.ref);
             // Compare type + name (drop origin — agent may omit origin prefix).
             if (expectedParsed.type !== actualParsed.type || expectedParsed.name !== actualParsed.name) {
                 emitReflectFailed("parse_error", "ref_mismatch", options.ref, {
                     expectedRef: options.ref,
                     actualRef: payload.ref,
                     ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+                    ...(reflectLlmTelemetry(result) ?? {}),
                 });
                 return {
-                    schemaVersion: 1,
+                    schemaVersion: 2,
                     ok: false,
                     reason: "parse_error",
                     error: `Agent retargeted proposal: expected ref "${options.ref}" but got "${payload.ref}". Proposal rejected to prevent silent ref hallucination.`,
                     ref: options.ref,
+                    engine: engineName,
                     exitCode: result.exitCode,
                     stdout: result.stdout,
                     ...(result.stderr ? { stderr: result.stderr } : {}),
@@ -1184,251 +1603,21 @@ export async function akmReflect(options = {}) {
             }
         }
         catch {
-            // parseAssetRef failure means the agent returned a malformed ref — already
+            // parseRefInput failure means the agent returned a malformed ref — already
             // caught downstream by createProposal; allow it to surface naturally.
         }
     }
-    // 7. R-5 / #374: Apply the proposal quality gate when enabled.
-    // Mirrors the lesson quality gate on distill proposals. The gate uses
-    // `runLessonQualityJudge` from distill.ts and is gated behind either
-    // `profiles.improve.default.processes.reflect.qualityGate.enabled` or
-    // `profiles.improve.default.processes.distill.qualityGate.enabled` (the
-    // `lesson_quality_gate` flag name is the legacy alias still accepted by
-    // `isLlmFeatureEnabled`). Fail-CLOSED (07 P0-2): a judge error / no-LLM /
-    // parse failure rejects the proposal rather than passing it through.
-    // G-Eval (arXiv:2303.16634) — quality judgment before admission.
-    const runtimeConfig = options.config ??
-        (() => {
-            try {
-                return loadConfig();
-            }
-            catch {
-                return undefined;
-            }
-        })();
-    const chatFn = options.chat ?? chatCompletion;
-    const qualityGateEnabled = isLlmFeatureEnabled(runtimeConfig, "proposal_quality_gate") ||
-        isLlmFeatureEnabled(runtimeConfig, "lesson_quality_gate");
-    if (qualityGateEnabled && runtimeConfig) {
-        const assetContent = (() => {
-            if (!options.ref)
-                return null;
-            try {
-                const refParsed = parseAssetRef(options.ref);
-                const candidates = [
-                    path.join(stash, `${refParsed.type}s`, `${refParsed.name}.md`),
-                    path.join(stash, `${refParsed.type}s`, refParsed.name, "index.md"),
-                ];
-                for (const p of candidates) {
-                    if (fs.existsSync(p))
-                        return fs.readFileSync(p, "utf8");
-                }
-                return null;
-            }
-            catch {
-                return null;
-            }
-        })();
-        const judgeResult = await runLessonQualityJudge(runtimeConfig, payload.content, assetContent ?? "", chatFn);
-        if (!judgeResult.pass) {
-            // Quality gate rejected the proposal — surface as parse_error so the
-            // improve orchestrator can log it and move on without crashing.
-            appendEvent({
-                eventType: "reflect_completed",
-                ref: payload.ref,
-                metadata: {
-                    source: "reflect",
-                    qualityRejected: true,
-                    qualityScore: judgeResult.score,
-                    qualityReason: judgeResult.reason,
-                },
-            });
-            return {
-                schemaVersion: 1,
-                ok: false,
-                reason: "parse_error",
-                error: `Reflect proposal quality gate rejected: score=${judgeResult.score}, reason="${judgeResult.reason}"`,
-                ...(options.ref ? { ref: options.ref } : {}),
-                exitCode: result.exitCode,
-            };
-        }
-    }
-    // 7b. Reflect content-preservation rails:
-    //     - Restore source frontmatter so reflect can never strip indexable
-    //       fields (`description`, `when_to_use`, `tags`, ...).
-    //     - Reset protected identity fields (`name`, `ref`, `id`, `slug`,
-    //       `type`) the LLM tried to change.
-    //     - Reject proposals that shrink/expand the body past safe ratios.
-    //
-    // See REFLECT_ALLOWED_TYPES / sanitizeReflectPayload for the underlying
-    // hypotheses + observed regressions (`8737ab63`, `26941510`, and the
-    // catastrophic-shrinkage cases from the May 2026 review).
-    const sanitizeOutcome = sanitizeReflectPayload({ content: payload.content, ...(payload.frontmatter ? { frontmatter: payload.frontmatter } : {}) }, assetContent, payload.ref);
-    if (sanitizeOutcome.reject) {
-        appendEvent({
-            eventType: "reflect_completed",
-            ref: payload.ref,
-            metadata: {
-                source: "reflect",
-                sanitized: true,
-                rejected: true,
-                rejectReason: sanitizeOutcome.reject.error,
-                ...(sanitizeOutcome.warnings.length > 0 ? { sanitizerWarnings: sanitizeOutcome.warnings } : {}),
-            },
-        });
-        return {
-            schemaVersion: 1,
-            ok: false,
-            reason: sanitizeOutcome.reject.reason,
-            error: sanitizeOutcome.reject.error,
-            ...(options.ref ? { ref: options.ref } : {}),
-            exitCode: result.exitCode,
-        };
-    }
-    payload = {
-        ...payload,
-        content: sanitizeOutcome.content,
-        ...(sanitizeOutcome.frontmatter ? { frontmatter: sanitizeOutcome.frontmatter } : {}),
-    };
-    // 7c. Noise gate (#580): never queue a proposal whose sanitized content is
-    // identical to the current asset (empty diff) or differs only cosmetically
-    // (whitespace reflow, code-fence language hints, YAML scalar re-folding).
-    // Pure deterministic text comparison — see `reflect-noise.ts`. Runs before
-    // the draftMode branch so self-consistency sampling never votes a no-op
-    // candidate into the queue either. Skipped when there is no source asset
-    // (new-asset proposals have nothing to diff against).
-    if (assetContent !== undefined) {
-        const changeKind = classifyReflectChange(assetContent, payload.content);
-        // 'low-value' is config-gated (#639). DEFAULT OFF — absent = byte-identical
-        // pre-#639 behaviour (low-value treated the same as substantive). Resolved
-        // by the caller from the ACTIVE improve profile's
-        // `processes.reflect.lowValueFilter.enabled` and passed via options, so the
-        // running profile (not a hardcoded `profiles.improve.default`) decides.
-        const lowValueFilterEnabled = options.lowValueFilter === true;
-        const isDeferred = changeKind === "noop" || changeKind === "cosmetic" || (changeKind === "low-value" && lowValueFilterEnabled);
-        if (isDeferred) {
-            const subreason = changeKind === "noop"
-                ? "reflect_skipped_noop"
-                : changeKind === "low-value"
-                    ? "reflect_skipped_low_value"
-                    : "reflect_skipped_cosmetic";
-            emitReflectFailed("no_change", subreason, options.ref, { changeKind });
-            return {
-                schemaVersion: 1,
-                ok: false,
-                reason: "no_change",
-                error: changeKind === "noop"
-                    ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
-                    : changeKind === "low-value"
-                        ? `Reflect skipped: proposed content for ${payload.ref} is a low-value prose micro-rewrite (few changed tokens, no structural changes); no proposal created.`
-                        : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
-                ...(options.ref ? { ref: options.ref } : {}),
-                exitCode: result.exitCode,
-            };
-        }
-    }
-    // 8. Create the proposal. The proposal queue is the ONLY thing reflect
-    // writes — promotion to a real asset is gated by `akm proposal accept`.
-    //
-    // R-4 / #373: Stamp `derived_from_reflect: true` in the frontmatter of any
-    // lesson proposal generated by reflect. This provenance marker lets
-    // `readRelatedLessons` exclude echo-chamber lessons (lessons that originate
-    // from prior reflect runs on the same skill) unless independent feedback
-    // evidence exists. ExpeL arXiv:2308.10144 — reject rules without success/
-    // failure differential from independent evidence.
-    const isLessonProposal = (() => {
-        try {
-            return parseAssetRef(payload.ref).type === "lesson";
-        }
-        catch {
-            return false;
-        }
-    })();
-    const basePayloadFrontmatter = payload.frontmatter ?? {};
-    const payloadFrontmatterWithProvenance = isLessonProposal
-        ? { ...basePayloadFrontmatter, derived_from_reflect: true }
-        : basePayloadFrontmatter;
-    // Draft mode: skip DB persistence — the SC sampling loop in improve.ts persists
-    // only the majority-vote winner (R-2 / #389). Return a synthetic proposal so
-    // pickMajorityVote can compare content via Jaccard similarity.
-    if (options.draftMode) {
-        const draftProposal = {
-            id: `sc-draft-${Date.now()}`,
-            ref: payload.ref,
-            source: "reflect",
-            status: "pending",
-            createdAt: new Date().toISOString(),
-            updatedAt: new Date().toISOString(),
-            payload: {
-                content: payload.content,
-                ...(Object.keys(payloadFrontmatterWithProvenance).length > 0
-                    ? { frontmatter: payloadFrontmatterWithProvenance }
-                    : {}),
-            },
-            // Phase 6A: preserve confidence on the synthetic draft so the SC majority
-            // winner carries the score through to the persisted proposal.
-            ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
-        };
-        return {
-            schemaVersion: 1,
-            ok: true,
-            proposal: draftProposal,
-            ref: draftProposal.ref,
-            agentProfile: resolvedProfileName,
-            durationMs: result.durationMs,
-        };
-    }
-    const createInput = {
-        ref: payload.ref,
-        source: "reflect",
-        sourceRun: `reflect-${Date.now()}`,
-        payload: {
-            content: payload.content,
-            ...(Object.keys(payloadFrontmatterWithProvenance).length > 0
-                ? { frontmatter: payloadFrontmatterWithProvenance }
-                : {}),
-        },
-        // Phase 6A: forward LLM-reported confidence into the proposal record.
-        // `parseAgentProposalPayload` already clamps to [0, 1] and drops non-
-        // finite values; `createProposal` runs its own sanitizer as a safety net.
-        ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
-        // Attribution tagging: persist the eligibility lane on the proposal so it
-        // survives to accept/reject/revert time even across runs. See EligibilitySource.
-        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
-    };
-    const proposalResult = createProposal(stash, createInput, options.ctx);
-    if (isProposalSkipped(proposalResult)) {
-        // Dedup/cooldown guard fired — surface as a "cooldown" reason (not "parse_error")
-        // so the improve orchestrator can distinguish legitimate skips from real failures
-        // and exclude them from recentErrors/avoidPatterns injection.
-        emitReflectFailed("cooldown", "proposal_skipped", options.ref, {
-            proposalSkipReason: proposalResult.reason,
-        });
-        return {
-            schemaVersion: 1,
-            ok: false,
-            reason: "cooldown",
-            error: `Proposal skipped (${proposalResult.reason}): ${proposalResult.message}`,
-            ...(options.ref ? { ref: options.ref } : {}),
-            exitCode: null,
-        };
-    }
-    const proposal = proposalResult;
-    appendEvent({
-        eventType: "reflect_completed",
-        ref: proposal.ref,
-        metadata: {
-            proposalId: proposal.id,
-            source: "reflect",
-            agentProfile: resolvedProfileName,
-        },
+    return finalizeReflectProposal({
+        payload,
+        assetContent,
+        result,
+        options,
+        engineName,
+        config,
+        activeStrategy,
+        runnerSpec,
+        feedback,
+        stash,
+        emitReflectFailed,
     });
-    return {
-        schemaVersion: 1,
-        ok: true,
-        proposal,
-        ref: proposal.ref,
-        agentProfile: resolvedProfileName,
-        durationMs: result.durationMs,
-    };
 }