akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/session-asset.js

@@ -2,37 +2,18 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Session asset generation for the `extract` pass (#561).
- *
- * After the extractor distills memory proposals from a session, it ALSO writes
- * the session itself to the stash as a first-class `session` asset so any agent
- * — on any harness — can discover prior work via `akm search` / `akm curate`.
- *
- * Design constraints (see #561):
- *   - ADDITIVE + FAIL-OPEN + CONFIG-GATED. Disabled (or no LLM provider) →
- *     extract behaves EXACTLY as before. Nothing is written.
- *   - The LLM summary call routes through the injectable {@link SessionSummaryGenerator}
- *     seam so tests never touch a real provider, and so production wraps the
- *     call in the existing `tryLlmFeature` fail-open pattern.
- *   - The `log_path` + `access` frontmatter fields are the durable correlation
- *     key — they survive index rebuilds (the body is re-derived from disk).
- *
- * The asset is written to `sessions/<harness>/<session-id>.md`; the registered
- * `session` asset type (see `asset-spec.ts`) makes the normal index pass pick it
- * up for FTS + vector search with no special-casing.
+ * Session assets (#561): besides its memory proposals, extract writes each
+ * session to `sessions/<harness>/<session-id>.md` as a searchable `session`
+ * asset. Additive and fail-open — no summary means nothing is written — and
+ * `log_path` + `access` in the frontmatter tell any agent how to read the raw log.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { stashDirFor } from "../../core/asset/asset-placement.js";
 import { assembleAsset } from "../../core/asset/asset-serialize.js";
 import { conceptIdFromTypeName } from "../../core/asset/resolve-ref.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
 import { recordWrittenPath } from "../../core/write-provenance.js";
-/**
- * JSON Schema for the session-summary LLM call. Strict so providers that
- * support schema enforcement constrain the output upstream; the parser only
- * has to handle the happy path. `additionalProperties: false` drops any
- * hallucinated keys before parsing.
- */
 export const SESSION_SUMMARY_JSON_SCHEMA = {
     type: "object",
     required: ["summary", "key_topics"],
@@ -43,11 +24,7 @@ export const SESSION_SUMMARY_JSON_SCHEMA = {
         tags: { type: "array", items: { type: "string" } },
     },
 };
-/**
- * Render a compact transcript snippet from session events for the summary
- * prompt. Mirrors the extract transcript format but caps total length so the
- * summary prompt stays bounded regardless of session size.
- */
+/** The transcript for the summary prompt, capped at `maxChars`. */
 function renderTranscriptForSummary(events, maxChars = 12_000) {
     if (events.length === 0)
         return "(empty — no events)";
@@ -66,11 +43,6 @@ function renderTranscriptForSummary(events, maxChars = 12_000) {
     }
     return lines.join("\n\n") || "(empty — no textual events)";
 }
-/**
- * Build the user prompt for the session-summary LLM call. Pure — no IO. The
- * model is asked for a dense 2–4 sentence summary plus key topics, optimised
- * for semantic search recall.
- */
 export function buildSessionSummaryPrompt(data) {
     const ref = data.ref;
     const startedAt = isoOrUndefined(ref.startedAt) ?? "unknown";
@@ -92,33 +64,13 @@ export function buildSessionSummaryPrompt(data) {
         'Respond as JSON: {"summary": string, "key_topics": string[], "tags"?: string[]}.',
     ].join("\n");
 }
-/**
- * Parse the session-summary LLM response into a {@link SessionSummaryResult}.
- * Defensive: tolerates prose preamble/postamble around the JSON, and returns
- * `undefined` when nothing usable parses (fail-open: no asset is written).
- */
+/** The summary JSON, tolerating prose around it; `undefined` when nothing usable parses. */
 export function parseSessionSummary(raw) {
     if (!raw || raw.trim().length === 0)
         return undefined;
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    }
-    catch {
-        const start = raw.indexOf("{");
-        const end = raw.lastIndexOf("}");
-        if (start === -1 || end <= start)
-            return undefined;
-        try {
-            parsed = JSON.parse(raw.slice(start, end + 1));
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (!parsed || typeof parsed !== "object")
+    const obj = parseEmbeddedJsonResponse(raw);
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
         return undefined;
-    const obj = parsed;
     const summary = typeof obj.summary === "string" ? obj.summary.trim() : "";
     if (summary.length === 0)
         return undefined;
@@ -130,62 +82,40 @@ export function parseSessionSummary(raw) {
         : undefined;
     return { summary, keyTopics, ...(tags && tags.length > 0 ? { tags } : {}) };
 }
-/**
- * Decide whether a session is long enough to index. `minDurationMinutes <= 0`
- * disables the gate. When either timestamp is missing we DON'T gate it out —
- * fail-open toward indexing, since a missing timestamp is not evidence of a
- * trivial session.
- */
+/** Long enough to index (`<= 0` disables; a missing timestamp is no evidence of a trivial session). */
 export function sessionMeetsDurationGate(data, minDurationMinutes) {
     if (!Number.isFinite(minDurationMinutes) || minDurationMinutes <= 0)
         return true;
     const { startedAt, endedAt } = data.ref;
     if (typeof startedAt !== "number" || typeof endedAt !== "number")
         return true;
-    const durationMinutes = (endedAt - startedAt) / 60_000;
-    return durationMinutes >= minDurationMinutes;
+    return (endedAt - startedAt) / 60_000 >= minDurationMinutes;
 }
-/**
- * Build per-harness `access` instructions for reading the raw session log.
- *
- * Documented convention (#561, checklist item "Document `access` field
- * convention per harness"): the string tells a downstream agent exactly how to
- * read and parse the source at `log_path`. New harnesses fall back to a generic
- * `cat <log_path>` hint for file-backed logs.
- */
+/** How an agent reads and parses the raw log at `log_path`, per harness (`cat` otherwise). */
 export function buildSessionAccessInstructions(harness, logPath, sessionId) {
-    const canonical = harness;
-    if (canonical === "claude") {
+    if (harness === "claude") {
         return [
             `Read with: cat ${logPath}`,
             `Parse messages: jq -r 'select(.type=="message") | .message.content[]? | select(.type=="text") | .text' ${logPath}`,
         ].join("\n");
     }
-    if (canonical === "opencode") {
+    if (harness === "opencode") {
         return [
             `Open the SQLite database at ${JSON.stringify(logPath)} in read-only mode.`,
             "Query: SELECT m.data, p.data FROM message AS m JOIN part AS p ON p.message_id = m.id WHERE m.session_id = ? AND p.session_id = ? ORDER BY m.time_created, p.time_created;",
             `Bind both parameters to ${JSON.stringify(sessionId)}.`,
         ].join("\n");
     }
-    // Generic fallback — file-backed logs are always readable with cat.
     return `Read with: cat ${logPath}`;
 }
-/** ISO-8601 (UTC) from a ms-epoch, or undefined when absent/non-finite. */
 function isoOrUndefined(ms) {
     return typeof ms === "number" && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;
 }
 /** Default session-name slug: `<harness>-session-<yyyy-mm-dd>-<shortId>`. */
 export function buildSessionAssetName(harness, sessionId, startedAtMs) {
-    const canonical = harness;
-    const datePart = isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date";
-    const shortId = sessionId.slice(0, 8);
-    return `${canonical}-session-${datePart}-${shortId}`;
+    return `${harness}-session-${isoOrUndefined(startedAtMs)?.slice(0, 10) ?? "unknown-date"}-${sessionId.slice(0, 8)}`;
 }
-/**
- * Assemble the full session asset (frontmatter + `## Summary` / `## Key topics`).
- * Pure — no IO. Returns the serialized markdown string.
- */
+/** The session asset: frontmatter plus `## Summary` and `## Key topics`. */
 export function buildSessionAssetContent(data, summary) {
     const ref = data.ref;
     const harness = ref.harness;
@@ -213,8 +143,7 @@ export function buildSessionAssetContent(data, summary) {
         .map((t) => `- ${t.trim()}`)
         .join("\n");
     const body = `## Summary\n\n${summary.summary.trim()}\n\n## Key topics\n\n${topics || "- (none extracted)"}\n`;
-    // `description` is duplicated into frontmatter so the metadata pass surfaces
-    // it without re-reading the body — matches how other content types behave.
+    // The summary doubles as the description, as for other types.
     const content = assembleAsset({ ...frontmatter, description: summary.summary.trim() }, body);
     return { name, frontmatter, content };
 }
@@ -223,13 +152,7 @@ export function resolveSessionAssetPath(stashDir, harness, sessionId) {
     const dir = stashDirFor("session") ?? "sessions";
     return path.join(stashDir, dir, harness, `${sessionId}.md`);
 }
-/**
- * Generate (via the injected summarizer) and write a session asset to the stash.
- *
- * FAIL-OPEN: when the summarizer returns `undefined` (disabled / no LLM /
- * error), NOTHING is written and `{ written: false }` is returned. Any write
- * error is swallowed by the caller — session indexing must NEVER break extract.
- */
+/** Summarize and write a session asset; nothing without a summary. The caller swallows write errors. */
 export async function writeSessionAsset(data, stashDir, generate) {
     const summary = await generate(data);
     if (!summary?.summary || summary.summary.trim().length === 0) {
@@ -241,15 +164,11 @@ export async function writeSessionAsset(data, stashDir, generate) {
     const filePath = resolveSessionAssetPath(stashDir, harness, sessionId);
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, content, "utf8");
-    // #652: extract's session asset is written outside the proposal queue —
-    // journal it so the run's auto-sync stages it as one of its own writes.
+    // Written outside the proposal queue: journal it so auto-sync commits it (#652).
     recordWrittenPath(filePath);
     return {
         written: true,
         filePath,
-        // Canonical 0.9.0 conceptId (`sessions/<harness>/<id>`, D-R3) — the same
-        // spelling the xrefs / usage-event readers now expect. Historical
-        // `session:<harness>/<id>` rows persist un-migrated and are tolerated.
         ref: conceptIdFromTypeName("session", `${harness}/${sessionId}`),
         logPath: data.ref.filePath,
     };

package/dist/commands/improve/stage.js

@@ -0,0 +1,322 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { getImproveProcessConfig } from "../../core/config/config.js";
+import { ConfigError } from "../../core/errors.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { warn } from "../../core/warn.js";
+import { LlmCallError } from "../../llm/client.js";
+import { callStructured } from "../../llm/structured-call.js";
+import { withLlmStage } from "../../llm/usage-telemetry.js";
+import { isProceduralRejection } from "../proposal/proposal-types.js";
+import { createProposal, listProposalsReadOnly, proposalContentHash, recordGateDecision, } from "../proposal/repository.js";
+import { resolveImproveLlmExecution } from "./execution.js";
+/** Normalize an unknown thrown value to a message. */
+export function errMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** The lowering notices a stage's dispatches emitted, each once. */
+export function noticeSet(forward) {
+    const byKey = new Map();
+    const add = (notices) => {
+        for (const notice of notices)
+            byKey.set(JSON.stringify(notice), notice);
+        forward?.(notices);
+    };
+    const list = () => Object.freeze([...byKey.values()]);
+    return { add, list, fields: () => (byKey.size > 0 ? { notices: list() } : {}) };
+}
+/**
+ * A stage's LLM runner: the one the improve plan froze for it (an own
+ * `llmRunner` key, `null` meaning "none"), else the process engine cascade.
+ */
+export function stageRunner(frozen, config, profile, processName, onNotices) {
+    if (Object.hasOwn(frozen, "llmRunner"))
+        return frozen.llmRunner ?? undefined;
+    const resolved = resolveImproveLlmExecution({
+        config,
+        profile,
+        process: getImproveProcessConfig(processName, profile),
+        processName,
+    });
+    if (resolved)
+        onNotices?.(resolved.notices);
+    return resolved?.runner;
+}
+/**
+ * One model call. Provider trouble (transport error, timeout, a disabled
+ * feature) comes back as `{ ok: false }`; only a configuration failure throws.
+ */
+export async function callStage(call) {
+    const messages = [
+        ...(call.system ? [{ role: "system", content: call.system }] : []),
+        ...(call.history ?? []),
+        { role: "user", content: call.prompt },
+    ];
+    let failure;
+    try {
+        const raw = await callStructured({
+            feature: call.feature,
+            ...(call.gate
+                ? { akmConfig: call.gate.config, ...(call.gate.enabled !== undefined ? { enabled: call.gate.enabled } : {}) }
+                : {}),
+            runner: call.runner,
+            messages,
+            ...(call.request ? { request: call.request } : {}),
+            ...(call.onNotices ? { onNotices: call.onNotices } : {}),
+            parse: (r) => r ?? "",
+            onError: (_cls, err) => {
+                failure = { ok: false, reason: "error", error: errMessage(err) };
+                return undefined;
+            },
+            fallback: undefined,
+            onFallback: (event) => {
+                failure ??= { ok: false, reason: event.reason, ...(event.error ? { error: event.error.message } : {}) };
+            },
+        });
+        return raw === undefined ? (failure ?? { ok: false, reason: "error" }) : { ok: true, raw };
+    }
+    catch (err) {
+        if (err instanceof ConfigError)
+            throw err;
+        const timedOut = err instanceof LlmCallError && err.code === "timeout";
+        return { ok: false, reason: timedOut ? "timeout" : "error", error: errMessage(err) };
+    }
+}
+/** Attribute a stage's LLM calls to its process and planned engine (the usage report). */
+const STAGE_LABELS = {
+    reflect: "reflect",
+    distill: "distill",
+    consolidate: "consolidate",
+    extract: "session-extraction",
+    memoryInference: "memory-inference",
+    validation: "validation",
+};
+export function attributeStage(plan, process, fn) {
+    return withLlmStage(STAGE_LABELS[process], fn, { engine: plan?.processes[process].runner?.engine, process });
+}
+/** How many prior rejected proposals are shown to the model as "don't repeat this". */
+export const MAX_REJECTED_PROPOSALS = 3;
+/**
+ * Reflexion context: the newest reviewer rejections for `ref`. Procedural
+ * refusals (expiry, stale target, missing asset) are not judgements on the
+ * content and are left out. Reads never create state.db.
+ */
+export function rejectedProposalContext(stash, ref, ctx) {
+    if (!ref)
+        return [];
+    return listProposalsReadOnly(stash, { ref, status: "rejected", includeArchive: true }, ctx)
+        .filter((p) => !isProceduralRejection(p))
+        .sort((a, b) => new Date(b.updatedAt ?? 0).getTime() - new Date(a.updatedAt ?? 0).getTime())
+        .slice(0, MAX_REJECTED_PROPOSALS)
+        .map((p) => ({
+        ref: p.ref,
+        reason: p.review?.reason ?? "no reason given",
+        // `payload.content` is populated on every row, including legacy ones.
+        contentPreview: p.payload.content.slice(0, 500),
+    }));
+}
+// ── Mint ─────────────────────────────────────────────────────────────────────
+/**
+ * Create a stage's proposal. `judged` stamps a `staged` gate decision with the
+ * judged content's hash (the triage drain accepts it while the content still
+ * matches); `review` leaves it `deferred` for a human (`review_needed` in the
+ * improve ledger).
+ */
+export function mintProposal(stash, proposalsCtx, input, verdict = {}) {
+    const proposal = createProposal(stash, input, proposalsCtx);
+    if (verdict.review) {
+        return recordGateDecision(stash, proposal.id, { outcome: "deferred", ...verdict.review }, proposalsCtx) ?? proposal;
+    }
+    return verdict.judged ? stageJudgedProposal(stash, proposal, proposalsCtx) : proposal;
+}
+/**
+ * Stamp a proposal the quality judge passed. Best-effort: a failed stamp only
+ * means the triage drain judges it again.
+ */
+export function stageJudgedProposal(stash, proposal, proposalsCtx) {
+    try {
+        return (recordGateDecision(stash, proposal.id, {
+            outcome: "staged",
+            reason: "quality-judge",
+            gate: "quality-gate",
+            contentHash: proposalContentHash(proposal),
+        }, proposalsCtx) ?? proposal);
+    }
+    catch (error) {
+        warn(`[akm] failed to record the quality-judge pass for ${proposal.id}: ${errMessage(error)}`);
+        return proposal;
+    }
+}
+/** Lesson judge prompt; similar existing lessons let it mark near-duplicates down. */
+export function buildJudgePrompt(lessonContent, sourceContent, similarLessons) {
+    const lines = [
+        "You are evaluating a proposed lesson asset for an akm knowledge base.",
+        "",
+        "Score this lesson on each criterion from 1 (poor) to 5 (excellent):",
+        "1. NOVELTY: Does the lesson add information not already present in the source asset?",
+        "2. NON-REDUNDANCY: Is this lesson meaningfully different from what the source already says?",
+        "",
+        "Source asset content:",
+        "```",
+        sourceContent.slice(0, 2000),
+        "```",
+    ];
+    if (similarLessons && similarLessons.length > 0) {
+        lines.push("", "Existing similar lessons (top-3 by similarity). Rate lower if the proposed lesson is substantially similar to any of these:");
+        for (const sl of similarLessons)
+            lines.push(`\nExisting lesson ref: ${sl.ref}`, "```", sl.content.slice(0, 500), "```");
+    }
+    lines.push("", "Proposed lesson content:", "```", lessonContent.slice(0, 1000), "```", "", 'Return ONLY valid JSON, no prose: {"scores": {"novelty": <1-5 integer>, "nonRedundancy": <1-5 integer>}, "reason": "<one sentence>"}');
+    return lines.join("\n");
+}
+function boundedDocument(content, maxChars = 6000) {
+    if (content.length <= maxChars)
+        return content;
+    const half = Math.floor((maxChars - 80) / 2);
+    return `${content.slice(0, half)}\n\n[... middle omitted for bounded judge context ...]\n\n${content.slice(-half)}`;
+}
+function buildChangedRegion(sourceContent, candidateContent) {
+    const source = sourceContent.split("\n");
+    const candidate = candidateContent.split("\n");
+    let prefix = 0;
+    while (prefix < source.length && prefix < candidate.length && source[prefix] === candidate[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < source.length - prefix &&
+        suffix < candidate.length - prefix &&
+        source[source.length - 1 - suffix] === candidate[candidate.length - 1 - suffix]) {
+        suffix++;
+    }
+    const removed = source.slice(prefix, source.length - suffix).join("\n");
+    const added = candidate.slice(prefix, candidate.length - suffix).join("\n");
+    return boundedDocument(`Removed or replaced:\n${removed || "(none)"}\n\nAdded or replacement:\n${added || "(none)"}`);
+}
+/** Judge prompt for an in-place revision (overlap with the source is expected). */
+export function buildReflectJudgePrompt(candidateContent, sourceContent, feedback) {
+    return [
+        "You are evaluating a proposed revision to an existing akm asset.",
+        "",
+        "Score this revision on each criterion from 1 (poor) to 5 (excellent):",
+        "1. FEEDBACK ALIGNMENT: Does the revision address the supplied feedback or improve retrieval and clarity?",
+        "2. PRESERVATION: Does it retain the source's concrete facts, code, commands, examples, and structure without truncation?",
+        "3. QUALITY: Is the revision coherent, actionable, complete, and free of unsupported claims?",
+        "",
+        "Overlap with the source is expected and must not lower the score by itself; this is an in-place revision, not a new lesson.",
+        "",
+        "Feedback:",
+        "```",
+        (feedback.length > 0 ? feedback.join("\n") : "No explicit feedback supplied.").slice(0, 1000),
+        "```",
+        "",
+        "Source asset content:",
+        "```",
+        boundedDocument(sourceContent),
+        "```",
+        "",
+        "Proposed revision:",
+        "```",
+        boundedDocument(candidateContent),
+        "```",
+        "",
+        "Changed region:",
+        "```",
+        buildChangedRegion(sourceContent, candidateContent),
+        "```",
+        "",
+        'Return ONLY valid JSON, no prose: {"scores": {"feedbackAlignment": <1-5 integer>, "preservation": <1-5 integer>, "quality": <1-5 integer>}, "reason": "<one sentence>"}',
+    ].join("\n");
+}
+const LESSON_JUDGE_CRITERIA = ["novelty", "nonRedundancy"];
+const REFLECT_JUDGE_CRITERIA = ["feedbackAlignment", "preservation", "quality"];
+/**
+ * Read a judge response: the per-criterion shape (averaged here) or the older
+ * `{"score"}` shape. Only the expected criteria are read; any missing or
+ * out-of-range (1..5) value is a parse failure, extra keys are ignored.
+ */
+function parseJudgeResponse(raw, keys) {
+    const parsed = parseEmbeddedJsonResponse(raw);
+    if (!parsed || typeof parsed.reason !== "string")
+        return undefined;
+    const reason = parsed.reason;
+    const inRange = (value) => typeof value === "number" && Number.isFinite(value) && value >= 1 && value <= 5;
+    if (parsed.scores !== undefined) {
+        if (typeof parsed.scores !== "object" || parsed.scores === null || Array.isArray(parsed.scores))
+            return undefined;
+        const scores = parsed.scores;
+        const criteria = {};
+        for (const key of keys) {
+            const value = scores[key];
+            if (!inRange(value))
+                return undefined;
+            criteria[key] = value;
+        }
+        return { score: Object.values(criteria).reduce((a, b) => a + b, 0) / keys.length, reason, criteria };
+    }
+    return inRange(parsed.score) ? { score: parsed.score, reason } : undefined;
+}
+function judgeResponseSchema(keys) {
+    return {
+        type: "object",
+        required: ["scores", "reason"],
+        additionalProperties: false,
+        properties: {
+            scores: {
+                type: "object",
+                required: [...keys],
+                additionalProperties: false,
+                properties: Object.fromEntries(keys.map((key) => [key, { type: "integer", minimum: 1, maximum: 5 }])),
+            },
+            reason: { type: "string" },
+        },
+    };
+}
+/**
+ * The quality judge. Fails closed: no runner, an unparseable verdict or a
+ * provider failure never passes content. Bands: >= 3.5 pass, 2.5-3.5 review,
+ * < 2.5 reject. Temperature is pinned to 0 so verdicts do not flip.
+ */
+async function runQualityJudge(feature, config, prompt, keys, chat, options) {
+    const resolved = !options.runnerSelectionFrozen && !options.llmRunner
+        ? resolveImproveLlmExecution({ config, processName: `${feature}-judge` })
+        : null;
+    if (resolved)
+        options.onNotices?.(resolved.notices);
+    const runner = options.llmRunner ?? resolved?.runner;
+    if (!runner)
+        return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
+    const outcome = await callStage({
+        feature,
+        runner,
+        system: "Return only valid JSON. No prose.",
+        prompt,
+        request: {
+            enableThinking: false,
+            temperature: 0,
+            responseSchema: judgeResponseSchema(keys),
+            ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+            ...(chat ? { chat } : {}),
+        },
+        ...(options.onNotices ? { onNotices: options.onNotices } : {}),
+    });
+    if (!outcome.ok) {
+        return { pass: false, score: -1, reason: "judge timeout/error — routed to review", reviewNeeded: true };
+    }
+    const parsed = parseJudgeResponse(outcome.raw, keys);
+    if (!parsed)
+        return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
+    const { score, reason, criteria } = parsed;
+    const verdict = score >= 3.5 ? { pass: true } : score >= 2.5 ? { pass: false, reviewNeeded: true } : { pass: false };
+    return { ...verdict, score, reason, ...(criteria ? { criteria } : {}) };
+}
+/** Judge a proposed lesson (or knowledge promotion) against its source. */
+export function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
+    const prompt = buildJudgePrompt(lessonContent, sourceContent, options.similarLessons);
+    return runQualityJudge("lesson_quality_gate", config, prompt, LESSON_JUDGE_CRITERIA, chat, options);
+}
+/** Judge an in-place reflect revision without new-lesson novelty criteria. */
+export function runReflectQualityJudge(config, candidateContent, sourceContent, feedback, chat, options = {}) {
+    const prompt = buildReflectJudgePrompt(candidateContent, sourceContent, feedback);
+    return runQualityJudge("proposal_quality_gate", config, prompt, REFLECT_JUDGE_CRITERIA, chat, options);
+}

package/dist/commands/lint/base-linter.js

@@ -42,6 +42,7 @@ import { isArchivedRelPath } from "../../core/asset/memory-archive.js";
 import { conceptIdFromTypeName, typeNameFromConceptId } from "../../core/asset/resolve-ref.js";
 import { localDateStamp } from "../../core/common.js";
 import { containsRedactedContent, REDACTED_CONTENT_MARKER } from "../../core/content-safety.js";
+import { DERIVED_SUFFIX } from "../../core/recognition-util.js";
 import { findFenceRegions } from "./markdown-insertion.js";
 // ── Helpers ───────────────────────────────────────────────────────────────────
 /** Fold physically wrapped prose the same way a YAML plain scalar does. */
@@ -203,12 +204,14 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
         if (resolveRefPathInStash(relPath, refType, refName, root) !== null)
             return true;
     }
-    // #884: a memory pruned by `analyzeMemoryCleanup` was ARCHIVED, not deleted —
-    // its bytes and identity live on under `.akm/memory-cleanup/archive`. Inbound
-    // belief edges to it are satisfied, not dangling, so resolve the tombstone
-    // rather than reporting `missing-ref`. Checked only after every live location
-    // misses: a tombstone must never shadow a real file, and the scan then costs
-    // one directory read per root instead of one per ref.
+    // #884: an asset `analyzeMemoryCleanup` pruned, or (alpha.9) a consolidate
+    // pair-pass `retire` proposal or a promotion's source memory retired, was
+    // ARCHIVED, not deleted — its bytes and identity live on under
+    // `.akm/memory-cleanup/archive`. Inbound refs to it are satisfied, not
+    // dangling, so resolve the tombstone rather than reporting `missing-ref`.
+    // Checked only after every live location misses: a tombstone must never
+    // shadow a real file, and the scan then costs one directory read per root
+    // instead of one per ref.
     //
     // Existence ONLY. `resolveRefPathInStash` deliberately does NOT consult the
     // archive: it hands back a path callers MUTATE (SPEC-5 `--supersedes`
@@ -217,17 +220,36 @@ export function refExistsInAnyStash(relPath, refType, refName, stashRoots) {
     return memoryArchiveHasRef(refType, refName, stashRoots);
 }
 /**
- * True when `(refType, refName)` names a memory that prune archived in any
- * root. Mirrors `resolveRefPathInStash`'s candidate set so a ref that resolved
- * through the `.derived.md` twin (#882) still resolves once archived.
+ * The stash-relative files that satisfy a ref, in preference order: its own
+ * placement spellings, then, for a memory, the `<name>.derived.md` child (#882),
+ * so an edge to a parent whose plain `.md` is gone still reaches the child it was
+ * distilled into. This is lint's reachability rule only; the child owns
+ * `memories/<name>.derived`, never `memories/<name>`.
+ */
+function refPathCandidates(refType, typeDir, refName) {
+    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    if (refType !== "memory" || refName.endsWith(DERIVED_SUFFIX))
+        return candidates;
+    return [...candidates, assetPathForName(refType, typeDir, `${refName}${DERIVED_SUFFIX}`)];
+}
+/**
+ * True when `(refType, refName)` names an asset the cleanup archive holds a
+ * tombstone for, in any root. Mirrors `resolveRefPathInStash`'s candidate set
+ * so a memory ref that resolved through the `.derived.md` child (#882) still
+ * resolves once archived.
+ *
+ * Originally memory-only (#884: only `.derived` memories were ever pruned).
+ * 0.9.17-alpha.9 generalized `archiveCleanupCandidate` to any memory,
+ * knowledge or lesson file (a consolidate pair-pass `retire` proposal, or an
+ * accepted promotion's source memory), so this must check every type, not
+ * just `memory` — otherwise an xref to a retired knowledge or lesson asset
+ * reports `missing-ref` even though it resolves fine through the tombstone.
  */
 function memoryArchiveHasRef(refType, refName, stashRoots) {
-    if (refType !== "memory")
-        return false; // only memories are ever archived
     const typeDir = stashDirFor(refType);
     if (typeDir === undefined)
         return false;
-    const candidates = assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = refPathCandidates(refType, typeDir, refName);
     for (const root of stashRoots) {
         for (const candidate of candidates) {
             if (isArchivedRelPath(candidate, root))
@@ -241,8 +263,8 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  * the same reachability rules (in the same order) as
  * {@link refExistsInAnyStash}, which delegates here. Returns the absolute path
  * of the file that makes the ref "exist" — for a multi-file skill directory
- * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` twin
- * when the plain `.md` is absent (#882, see `assetPathCandidatesForName`) —
+ * that is its `SKILL.md` primary, for a `memory` ref its `.derived.md` child
+ * when the plain `.md` is absent (#882, see {@link refPathCandidates}) —
  * or `null` when the ref does not resolve in this root.
  *
  * Extracted for SPEC-5 (`--supersedes` demotion): write commands need the
@@ -253,7 +275,7 @@ function memoryArchiveHasRef(refType, refName, stashRoots) {
  */
 export function resolveRefPathInStash(relPath, refType, refName, root) {
     const typeDir = stashDirFor(refType);
-    const candidates = typeDir === undefined ? [relPath] : assetPathCandidatesForName(refType, typeDir, refName);
+    const candidates = typeDir === undefined ? [relPath] : refPathCandidates(refType, typeDir, refName);
     for (const candidate of candidates) {
         const absPath = path.join(root, candidate);
         if (fs.existsSync(absPath))