akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/commands/improve/reflect.js

@@ -26,8 +26,7 @@ import os from "node:os";
 import path from "node:path";
 import { assembleAssetFromString, serializeFrontmatter } from "../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../core/asset/frontmatter.js";
-import { stripMarkdownFences } from "../../core/asset/markdown.js";
-import { parseRefInput } from "../../core/asset/resolve-ref.js";
+import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { DESCRIPTION_MAX_CHARS, requiresDescription } from "../../core/authoring-rules.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError } from "../../core/errors.js";
@@ -36,8 +35,10 @@ 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 { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
+import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { 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";
@@ -54,7 +55,7 @@ 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 { bareImproveRef, durableImproveRef, improveStateReadRefs } from "./source-identity.js";
+import { durableImproveRef, improveStateReadRefs } from "./source-identity.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -63,10 +64,9 @@ const MAX_GLOBAL_FEEDBACK_LINES = 20;
  * all assets so `akm reflect` can operate in a general "review recent
  * signals" mode. Best-effort — a missing or empty events stream returns `[]`.
  */
-function readRecentFeedback(ref, legacyRef) {
+function readRecentFeedback(ref) {
     try {
-        const result = readEvents({ type: "feedback", ...(ref && !legacyRef ? { ref } : {}) });
-        const events = ref && legacyRef ? result.events.filter((event) => event.ref === ref || event.ref === legacyRef) : result.events;
+        const events = readEvents({ type: "feedback", ...(ref ? { ref } : {}) }).events;
         const lines = [];
         const limit = ref ? MAX_FEEDBACK_LINES : MAX_GLOBAL_FEEDBACK_LINES;
         for (const event of events.slice(-limit)) {
@@ -116,7 +116,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"]);
 /**
@@ -146,12 +146,13 @@ 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 +
@@ -194,13 +195,13 @@ 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(ctx, stash, ref, parsedRef, sourceName, itemRef, legacyBareState) {
+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)) {
         // 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,
@@ -208,16 +209,13 @@ async function readRelatedLessons(ctx, stash, ref, parsedRef, sourceName, itemRe
         related.set(derivedLessonRef, { ref: derivedLessonRef, content: ctx.readAsset(derivedLessonPath) });
     }
     try {
-        // Chunk-5 flip F5f (Step 6 readers) — dual-arm the distill_invoked filter on
-        // [item_ref, durable, bare] so an event keyed under EITHER grammar resolves
-        // once the writers emit item_ref. Dormant: item_ref NULL through improve
-        // today, so the key set is [durable] byte-identically. // Chunk-8: [item_ref].
-        const distillInvokedKeys = new Set(improveStateReadRefs(ref, sourceName, legacyBareState ?? false, itemRef));
+        // 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 {
@@ -225,7 +223,7 @@ async function readRelatedLessons(ctx, stash, ref, parsedRef, sourceName, itemRe
     }
     for (const candidateRef of candidateRefs) {
         try {
-            const filePath = await findAssetFilePath(durableImproveRef(candidateRef, sourceName), stash);
+            const filePath = await findAssetFilePath(durableImproveRef(candidateRef), stash);
             if (!filePath || !fs.existsSync(filePath))
                 continue;
             const content = ctx.readAsset(filePath);
@@ -245,7 +243,7 @@ async function readRelatedLessons(ctx, stash, ref, parsedRef, sourceName, itemRe
                 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 });
                 }
@@ -295,58 +293,22 @@ async function readRelatedLessons(ctx, stash, ref, parsedRef, sourceName, itemRe
 /**
  * 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" &&
-            // WI-6.4 vocabulary (fingerprint_match / rejection_backoff) plus the
-            // legacy tokens — old agent payloads may still carry the retired names.
-            [
-                "fingerprint_match",
-                "rejection_backoff",
-                "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.
- *
- * For SDK runners, 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]`
@@ -364,55 +326,6 @@ function lenientRefType(ref) {
         return "";
     }
 }
-function fallbackPayloadFromRawContent(stdout, ref, sdkRunner = false) {
-    if (!ref)
-        return undefined;
-    const trimmed = stripMarkdownFences(stdout).trim();
-    if (!trimmed)
-        return undefined;
-    const targetType = lenientRefType(ref);
-    if (!looksLikeAssetContent(trimmed, sdkRunner, 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.
- * - For SDK runners: additionally requires `when_to_use:` for
- *   lesson types (full structured output will replace this in a future PR).
- */
-function looksLikeAssetContent(value, sdkRunner = 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 (sdkRunner && targetType === "lesson") {
-            return /^when_to_use\s*:/m.test(fmBlock);
-        }
-        return true;
-    }
-    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;
-    }
-    return false;
-}
 /**
  * Split a markdown blob into `[frontmatterText, bodyText]`.
  *
@@ -824,9 +737,8 @@ function parseDirectReflectOutput(raw, mode, targetRef) {
  *
  * Returns an {@link AgentRunResult}-shaped object so it can slot into the same
  * dispatch loop as agent-based runners. Production calls extract the selected
- * direct-LLM contract and normalize it to proposal JSON in `stdout`; legacy
- * unit callers that omit `outputMode` retain raw stdout. Errors are captured
- * into the result rather than thrown.
+ * 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();
@@ -875,24 +787,13 @@ export async function runReflectViaLlm(opts) {
             exitCode,
             reason,
             error: msg,
-            ...(opts.outputMode ? { parsed: { outputMode: opts.outputMode, repairAttempts } } : {}),
+            parsed: { outputMode: opts.outputMode, repairAttempts },
         };
     };
     try {
         if (opts.signal?.aborted)
             throw new Error("Reflect request aborted");
         const stdout = await call(messages);
-        // Preserve the old raw-response seam for direct unit callers. Production
-        // akmReflect always sets outputMode and receives a normalized payload.
-        if (!opts.outputMode) {
-            return {
-                ok: true,
-                stdout,
-                stderr: "",
-                durationMs: Date.now() - start,
-                exitCode: 0,
-            };
-        }
         let payload;
         let acceptedOutput = stdout;
         try {
@@ -1112,6 +1013,7 @@ function createReflectProposal(args) {
         : basePayloadFrontmatter;
     const createInput = {
         ref: payload.ref,
+        ...(options.target ? { target: options.target } : {}),
         source: "reflect",
         sourceRun: `reflect-${Date.now()}`,
         payload: {
@@ -1173,12 +1075,11 @@ function createReflectProposal(args) {
 /**
  * Resolve the agent's proposal payload from a successful run: the file-write
  * contract path (read `lastDraftPath`, extract self-rated confidence) or the
- * legacy JSON-stdout path (`parseAgentProposalPayload`, with the raw-content
- * fallback and cooldown-signal reclassification). Returns the payload or a
- * terminal failure envelope. Extracted verbatim from `akmReflect`.
+ * JSON-stdout path used by direct LLM runners. Returns the payload or a terminal
+ * failure envelope.
  */
 function resolveReflectPayload(args) {
-    const { result, lastDraftPath, sensitiveValues, options, runnerSpec, engineName, emitReflectFailed } = 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
@@ -1187,9 +1088,7 @@ function resolveReflectPayload(args) {
     // 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.
+    // 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) {
@@ -1236,10 +1135,6 @@ function resolveReflectPayload(args) {
         return { payload: parseAgentProposalPayload(result.stdout ?? "") };
     }
     catch (err) {
-        const fallback = fallbackPayloadFromRawContent(result.stdout ?? "", options.ref, runnerSpec.kind === "sdk");
-        if (fallback) {
-            return { payload: fallback };
-        }
         // 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.
@@ -1292,11 +1187,17 @@ function resolveReflectRunner(options) {
         runnerSpec = processRunner;
     }
     else {
-        const defaultEngine = config.defaults?.engine;
+        const { config: engineConfig, fallbackEngineName } = withEngineFallback(config);
+        const defaultEngine = engineConfig.defaults?.engine;
+        // Announced, never silent — same contract as the workflow freeze boundary
+        // and the task runner. Only this arm can select the synthesized engine.
+        const engineAnnouncement = fallbackAnnouncement(fallbackEngineName, defaultEngine);
+        if (engineAnnouncement)
+            warn(engineAnnouncement);
         if (!defaultEngine) {
-            throw new ConfigError("reflect requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
+            throw new ConfigError(`reflect ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
         }
-        runnerSpec = resolveEngine(defaultEngine, config);
+        runnerSpec = resolveEngine(defaultEngine, engineConfig);
     }
     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.");
@@ -1335,7 +1236,7 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
                     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.`,
+                    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,
                 },
@@ -1347,10 +1248,9 @@ async function resolveReflectSource(options, stash, emitReflectFailed) {
         }
         else {
             try {
-                // Chunk-5 flip F5f — resolve the source asset by item_ref when the planner
-                // supplied one (the index entry carries it), else the pre-flip durable ref.
-                // Dormant: item_ref NULL today, so this reduces to the durable ref.
-                const qualifiedRef = options.itemRef ?? durableImproveRef(options.ref, options.sourceName);
+                // 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");
@@ -1420,7 +1320,7 @@ async function runReflectRefineIterations(args) {
             // 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).
+            // on long bodies (e.g. knowledge/systems/KOKORO_USAGE_GUIDE 8.4KB).
             ...(iterDraftPath ? { draftFilePath: iterDraftPath } : {}),
             ...(outputMode ? { outputMode } : {}),
         });
@@ -1448,10 +1348,10 @@ async function runReflectRefineIterations(args) {
                 ...(options.signal ? { signal: options.signal } : {}),
                 priorDraft,
                 iteration: iter,
-                ...(outputMode === "json_schema"
+                ...(spec.connection.supportsJsonSchema
                     ? { responseSchema: options.ref ? REFLECT_JSON_SCHEMA : REFLECT_UNSCOPED_JSON_SCHEMA }
                     : {}),
-                ...(outputMode ? { outputMode } : {}),
+                outputMode: spec.connection.supportsJsonSchema ? "json_schema" : "framed_markdown",
                 ...(options.ref ? { targetRef: options.ref } : {}),
                 allowRepair: repairAttempts === 0,
                 chat: options.chat,
@@ -1534,9 +1434,8 @@ function emitReflectInvokedAndBuildFailureEmitter(options) {
     // attempt regardless of downstream success/failure.
     appendEvent({
         eventType: "reflect_invoked",
-        // Chunk-5 flip F5f — key on item_ref when the planner resolved one, else the
-        // pre-flip source-qualified durable ref (dormant: item_ref NULL today).
-        ...(options.ref ? { ref: options.itemRef ?? durableImproveRef(options.ref, options.sourceName) } : {}),
+        // 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 } : {}),
@@ -1583,11 +1482,9 @@ export async function akmReflect(options = {}) {
     // 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 ? durableImproveRef(options.ref, options.sourceName) : undefined, options.ref && options.legacyBareState ? bareImproveRef(options.ref) : undefined);
+    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.sourceName, options.itemRef, options.legacyBareState)
-        : [];
+    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);
@@ -1603,7 +1500,7 @@ export async function akmReflect(options = {}) {
     });
     // 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 = [];
     // Best-effort unlink: tolerate already-deleted files (we may have unlinked
@@ -1668,7 +1565,6 @@ export async function akmReflect(options = {}) {
             lastDraftPath,
             sensitiveValues,
             options,
-            runnerSpec,
             engineName,
             emitReflectFailed,
         });
@@ -1686,8 +1582,8 @@ export async function akmReflect(options = {}) {
     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 parseRefInput (dual-grammar) 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 {

package/dist/commands/improve/salience.js

@@ -235,132 +235,21 @@ export function computeSalience(inputs) {
     const rankScore = Math.min(1, Math.max(0, rawRankScore));
     return { encoding, outcome, retrieval, rankScore, encodingSource };
 }
+// ── state.db persistence ─────────────────────────────────────────────────────
+//
+// The three sub-scores live in state.db::asset_salience. Raw SQL now lives in
+// storage/repositories/salience-repository.ts (#672 part 2) — extracted
+// verbatim, only relocated behind the repository boundary. Re-exported here so
+// existing importers of this module resolve unchanged. Migrations live in
+// state-db.ts (migration 009).
+export { getAllRankScores, getAssetSalience, getConsecutiveNoOps, recordNoOp, resetConsecutiveNoOps, upsertAssetSalience, } from "../../storage/repositories/salience-repository.js";
 /**
  * Does this row carry a genuine content-derived `encoding_salience` (#644)?
  *
- * Returns true when the provenance flag is `"content"`. For legacy rows
- * (`encoding_source === null`, written before migration 015) we apply a
- * conservative heuristic: treat the stored value as content-derived only when it
- * does NOT equal the pure type-weight stub for the asset's type — because before
- * the #644 fix every run overwrote real scores with the stub, a value that still
- * differs from the stub must have been content-written and never re-clobbered.
- * When the type cannot be determined (no `type` given) a null-provenance row is
- * treated as a stub (the safe default).
- */
-export function isContentEncodingRow(row, type) {
-    if (row.encoding_source === "content")
-        return true;
-    if (row.encoding_source === "type-stub")
-        return false;
-    // Legacy NULL provenance: differ-from-stub heuristic.
-    if (!type)
-        return false;
-    const stub = DEFAULT_TYPE_ENCODING_WEIGHTS[type] ?? DEFAULT_ENCODING_SALIENCE;
-    return Math.abs(row.encoding_salience - stub) > 1e-9;
-}
-/**
- * Upsert salience scores for one asset into state.db.
- *
- * Idempotent: safe to call every run; updates the outcome / retrieval / rank
- * columns on conflict.
- *
- * #644 — encoding provenance guard: the `encoding_salience` + `encoding_source`
- * columns are NOT lowered from a real content-derived score to a type-weight
- * stub. When the stored row is `encoding_source = 'content'` and the incoming
- * vector is a `type-stub` fallback, the stored encoding score and its provenance
- * are preserved (only the other sub-scores and `rank_score` advance). A `content`
- * write always wins; a `type-stub` write only seeds a row that has no content
- * score yet. This stops the improve loop's type-weight fallback re-asserting the
- * stub over a distill-written score on every run.
- *
- * NOTE: when the guard preserves the stored encoding score, the incoming
- * `vector.rankScore` (computed from the stub encoding) is still written. Callers
- * that want the rank_score to reflect the preserved content score should pass the
- * stored content score back in as `inputs.encodingSalience` to `computeSalience`
- * — which the improve loop does. The guard here is the defensive backstop.
- */
-export function upsertAssetSalience(db, ref, vector, now) {
-    const ts = now ?? Date.now();
-    db.prepare(`INSERT INTO asset_salience
-       (asset_ref, encoding_salience, outcome_salience, retrieval_salience, rank_score, consecutive_no_ops, updated_at, encoding_source)
-     VALUES (?, ?, ?, ?, ?, 0, ?, ?)
-     ON CONFLICT(asset_ref) DO UPDATE SET
-       -- #644: never lower a real content-derived score to a type-weight stub.
-       -- Keep the stored encoding score + provenance when the stored row is
-       -- 'content' and the incoming write is a 'type-stub' fallback.
-       encoding_salience  = CASE
-         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
-           THEN asset_salience.encoding_salience
-           ELSE excluded.encoding_salience
-       END,
-       encoding_source    = CASE
-         WHEN asset_salience.encoding_source = 'content' AND excluded.encoding_source = 'type-stub'
-           THEN asset_salience.encoding_source
-           ELSE excluded.encoding_source
-       END,
-       outcome_salience   = excluded.outcome_salience,
-       retrieval_salience = excluded.retrieval_salience,
-       rank_score         = excluded.rank_score,
-       updated_at         = excluded.updated_at`).run(ref, vector.encoding, vector.outcome, vector.retrieval, vector.rankScore, ts, vector.encodingSource ?? "type-stub");
-}
-/**
- * Load the salience row for one asset, or undefined if not yet computed.
- */
-export function getAssetSalience(db, ref) {
-    const row = db
-        .prepare(`SELECT asset_ref, encoding_salience, outcome_salience, retrieval_salience,
-              rank_score, consecutive_no_ops, updated_at, encoding_source
-       FROM asset_salience WHERE asset_ref = ?`)
-        .get(ref);
-    // Bun SQLite returns null (not undefined) when no row found.
-    return row == null ? undefined : row;
-}
-/**
- * Load ALL rank scores from the asset_salience table (full-stash query).
- *
- * Used by the forgetting-safety report (plan §WS-1 step 7) to compute stash-wide
- * rank positions rather than pool-relative positions. Returns an empty Map when the
- * table is empty (first WS-1 run = no pre-existing rows).
- *
- * Order is unspecified; callers must sort before assigning 1-indexed positions.
- */
-export function getAllRankScores(db) {
-    const rows = db.prepare("SELECT asset_ref, rank_score FROM asset_salience").all();
-    const result = new Map();
-    for (const row of rows) {
-        result.set(row.asset_ref, row.rank_score);
-    }
-    return result;
-}
-// ── Plasticity helpers ────────────────────────────────────────────────────────
-/**
- * Increment `consecutive_no_ops` for an asset. Called after a no-op reflect/distill.
- * Has NO effect on `rank_score` — the plasticity counter only dampens consolidation
- * selection, not retrieval ranking. See plan §WS-1 step 8.
- *
- * Invariant: recordNoOp must never originate rank_score semantics. If the asset has
- * no salience row yet (persistence's best-effort try/catch may have swallowed an
- * error), we do nothing — a no-op counter is meaningless without a rank_score row,
- * and a synthetic INSERT would fabricate a rank_score=0 entry that could produce
- * false catastrophic-forgetting signals in buildRankChangeReport.
- */
-export function recordNoOp(db, ref) {
-    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = consecutive_no_ops + 1, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
-    // If changes === 0 the asset has no salience row yet — leave the table unchanged.
-}
-/**
- * Reset `consecutive_no_ops` to 0 when an asset produces an accepted change.
- * Call after a successful proposal acceptance or detected mutation.
- */
-export function resetConsecutiveNoOps(db, ref) {
-    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = 0, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
-}
-/**
- * Return the `consecutive_no_ops` count for one asset. 0 when unknown.
+ * Unknown provenance is not treated as content-derived.
  */
-export function getConsecutiveNoOps(db, ref) {
-    const row = db.prepare(`SELECT consecutive_no_ops FROM asset_salience WHERE asset_ref = ?`).get(ref);
-    return row?.consecutive_no_ops ?? 0;
+export function isContentEncodingRow(row) {
+    return row.encoding_source === "content";
 }
 // ── Consolidation-selection dampener constants ────────────────────────────────
 //