akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/commands/improve/distill/quality-gate.js

@@ -1,337 +0,0 @@
-// 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/.
-/**
- * Distill quality-gate cluster — LLM-as-judge, quality-rejection envelope
- * writer, and output-salience persistence. Extracted verbatim from
- * `distill.ts` so the main `akmDistill` orchestrator and the memory→knowledge
- * promotion branch (`promote-memory.ts`) can share the same helpers without a
- * circular import. Logic is byte-identical to the pre-extraction inline code.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { parseRefInput } from "../../../core/asset/resolve-ref.js";
-import { timestampForFilename } from "../../../core/common.js";
-import { ConfigError } from "../../../core/errors.js";
-import { appendEvent } from "../../../core/events.js";
-import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
-import { getDistillRejectedDir } from "../../../core/paths.js";
-import { withStateDb } from "../../../core/state-db.js";
-import { recordWrittenPath } from "../../../core/write-provenance.js";
-import { callStructured } from "../../../llm/structured-call.js";
-import { akmSearch } from "../../read/search.js";
-import { scoreEncodingSalience } from "../encoding-salience.js";
-import { resolveImproveLlmExecution } from "../execution.js";
-import { computeSalience, upsertAssetSalience } from "../salience.js";
-// ── D-4 / #390: Top-3 similar lessons retrieval ──────────────────────────────
-/**
- * Default implementation: use akmSearch to find top-N similar lesson assets.
- * Returns empty array when search fails or returns no results.
- * Requires embedding configured for semantic similarity; degrades gracefully.
- */
-export async function fetchTopSimilarLessons(query, n, _stashDir) {
-    try {
-        const result = await akmSearch({
-            query,
-            type: "lesson",
-            limit: n,
-            skipLogging: true,
-            eventSource: "improve",
-        });
-        const hits = result?.hits ?? [];
-        return hits
-            .filter((h) => "path" in h && typeof h.path === "string")
-            .slice(0, n)
-            .map((h) => {
-            let content = "";
-            try {
-                if (h.path && fs.existsSync(h.path)) {
-                    content = fs.readFileSync(h.path, "utf8");
-                }
-            }
-            catch {
-                /* best-effort */
-            }
-            return { ref: h.ref, content };
-        });
-    }
-    catch {
-        return [];
-    }
-}
-// ── LLM-as-judge quality gate (P2-B) ────────────────────────────────────────
-/**
- * D-4 / #390: Build the LLM-as-judge prompt.
- *
- * When similarLessons are provided (top-3 by embedding similarity), they are
- * included in the context so the judge can lower the score for near-duplicates.
- * Voyager arXiv:2305.16291 — skill library admission requires similarity check
- * against the existing library. A-MEM arXiv:2502.12110 — new notes are checked
- * against existing notes before linking.
- */
-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. ACTIONABILITY: Can an agent follow this lesson without additional context?",
-        "3. 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("");
-        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}`);
-            lines.push("```");
-            lines.push(sl.content.slice(0, 500));
-            lines.push("```");
-        }
-    }
-    lines.push("");
-    lines.push("Proposed lesson content:");
-    lines.push("```");
-    lines.push(lessonContent.slice(0, 1000));
-    lines.push("```");
-    lines.push("");
-    lines.push('Return ONLY valid JSON, no prose: {"score": <average score 1-5 as float>, "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)"}`);
-}
-/** Build quality criteria for revising an existing asset in place. */
-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: {"score": <average score 1-5 as float>, "reason": "<one sentence>"}',
-    ].join("\n");
-}
-async function runQualityJudge(feature, config, prompt, chat, options = {}) {
-    const resolvedDefault = !options.runnerSelectionFrozen && !options.llmRunner
-        ? resolveImproveLlmExecution({ config, processName: `${feature}-judge` })
-        : null;
-    if (resolvedDefault)
-        options.onNotices?.(resolvedDefault.notices);
-    const runner = options.llmRunner ?? resolvedDefault?.runner;
-    if (!runner) {
-        return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
-    }
-    try {
-        // UNGATED at the seam (no akmConfig): the quality gates' enablement is
-        // resolved by the caller before this function runs, and a transport throw
-        // propagates into the fail-closed catch below. `feature` labels the call.
-        const raw = await callStructured({
-            feature,
-            runner,
-            ...(options.lease ? { lease: options.lease } : {}),
-            messages: [
-                { role: "system", content: "Return only valid JSON. No prose." },
-                { role: "user", content: prompt },
-            ],
-            request: {
-                enableThinking: false,
-                ...(Object.hasOwn(options, "timeoutMs") ? { timeoutMs: options.timeoutMs } : {}),
-                ...(options.signal ? { signal: options.signal } : {}),
-                ...(chat ? { chat } : {}),
-            },
-            parse: (rawResponse) => rawResponse ?? "",
-            // Unreachable on the ungated path (errors propagate); fail closed anyway.
-            onError: () => "",
-            fallback: "",
-            ...(options.onNotices ? { onNotices: options.onNotices } : {}),
-        });
-        const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed ||
-            typeof parsed.score !== "number" ||
-            !Number.isFinite(parsed.score) ||
-            parsed.score < 1 ||
-            parsed.score > 5 ||
-            typeof parsed.reason !== "string") {
-            return { pass: false, score: -1, reason: "judge parse failed — routed to review", reviewNeeded: true };
-        }
-        // D-5 / #388: Three-band system (MT-Bench arXiv:2306.05685 — ~±0.5 judge variance).
-        //   >= 3.5: auto-queue as pending (pass: true)
-        //   2.5–3.5: review-needed band — uncertain, escalate to human (reviewNeeded: true)
-        //   < 2.5: auto-reject (pass: false)
-        const score = parsed.score;
-        const reason = parsed.reason ?? "";
-        if (score >= 3.5)
-            return { pass: true, score, reason };
-        if (score >= 2.5)
-            return { pass: false, score, reason, reviewNeeded: true };
-        return { pass: false, score, reason };
-    }
-    catch (error) {
-        // Invalid symbolic credentials are configuration failures, not a negative
-        // content verdict. Provider/runtime failures retain the fail-closed result.
-        if (error instanceof ConfigError)
-            throw error;
-        return { pass: false, score: -1, reason: "judge timeout/error — routed to review", reviewNeeded: true };
-    }
-}
-/**
- * Run the LLM-as-judge quality gate on a proposal's content.
- *
- * Exported so reflect.ts can apply the same gate to reflect proposals (R-5 / #374).
- * The selected strategy's distill/reflect quality-gate setting is resolved by
- * the caller before this function runs.
- *
- * Fail-CLOSED (07 P0-2): returns `pass: false` (score -1) on timeout, parse
- * failure, or missing LLM. Minted content that cannot be judged is rejected,
- * not passed through — an unverifiable judge must never wave content into the
- * stash. The rejection is `quality_rejected`, not `review_needed`.
- */
-export async function runLessonQualityJudge(config, lessonContent, sourceContent, chat, options = {}) {
-    return runQualityJudge("lesson_quality_gate", config, buildJudgePrompt(lessonContent, sourceContent, options.similarLessons), chat, options);
-}
-/** Judge an in-place reflect revision without applying new-lesson novelty criteria. */
-export async function runReflectQualityJudge(config, candidateContent, sourceContent, feedback, chat, options = {}) {
-    return runQualityJudge("proposal_quality_gate", config, buildReflectJudgePrompt(candidateContent, sourceContent, feedback), chat, options);
-}
-// ── Quality-rejection helper ─────────────────────────────────────────────────
-/**
- * Write a rejected lesson to `$STATE/improve/distill-rejected/<stash>/`
- * (itlackey/akm#890), append a `distill_invoked` quality-rejected event, and
- * return the `quality_rejected` envelope.
- *
- * @param stash     - Root stash directory.
- * @param inputRef  - The original input ref (for the event).
- * @param proposalRef - The proposed lesson/knowledge ref.
- * @param content   - The raw content that failed the quality gate.
- * @param score     - Quality score from the judge.
- * @param reason    - Human-readable rejection reason.
- * @param extraMeta - Optional additional metadata for the event.
- * @param eventsCtx - Events context so the emit takes appendEvent's fast path (R25).
- */
-export function writeQualityRejection(stash, inputRef, proposalRef, content, score, reason, extraMeta = {}, eligibilitySource, eventsCtx) {
-    // D-5 / #388: reviewNeeded flag selects "review_needed" vs "quality_rejected" outcome.
-    const outcome = extraMeta.reviewNeeded ? "review_needed" : "quality_rejected";
-    const rejectDir = getDistillRejectedDir(stash);
-    fs.mkdirSync(rejectDir, { recursive: true });
-    const ts = timestampForFilename();
-    const rejectPath = path.join(rejectDir, `${ts}-${proposalRef.replace(/[:/\\]/g, "-")}.md`);
-    fs.writeFileSync(rejectPath, `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
-    // #652 / itlackey/akm#890: journal it even though it now lands under
-    // `$STATE`, outside the stash's git repo — `result.writtenPaths` reports
-    // every path a run touched, in or out of the stash (describeRunWrittenPaths
-    // in improve.ts falls back to the absolute path for anything outside the
-    // stash root), and the auto-sync commit's own containment check
-    // (resolveSyncPathSet's `relativeWrittenPath`) already drops anything
-    // outside `repoDir` from what gets staged — recording it here cannot cause
-    // it to be committed.
-    recordWrittenPath(rejectPath);
-    appendEvent({
-        eventType: "distill_invoked",
-        ref: inputRef,
-        metadata: {
-            outcome,
-            proposalRef,
-            score,
-            reason,
-            ...extraMeta,
-            // Attribution tagging: stamp the eligibility lane so distill_invoked can be
-            // sliced by lane downstream. See EligibilitySource.
-            ...(eligibilitySource ? { eligibilitySource } : {}),
-        },
-    }, eventsCtx);
-    return {
-        schemaVersion: 1,
-        ok: true,
-        outcome,
-        inputRef,
-        proposalRef,
-        score,
-        reason,
-        ...extraMeta,
-    };
-}
-/**
- * G4 — content-score a distilled OUTPUT (lesson/knowledge proposal body) and
- * persist it to state.db :: asset_salience with `encoding_source: "content"`.
- *
- * Lessons are refused as distill INPUTS (`DISTILL_REFUSED_INPUT_TYPES`), so
- * this creation-time write is their only chance to earn a real content-derived
- * encoding score instead of sitting on the type-weight stub forever. Best-effort:
- * never blocks or fails the proposal flow.
- */
-export function persistOutputEncodingSalience(ref, body, existingRefVocabulary, 
-// Operator opt-out (improve.salience.outcomeWeightEnabled: false) must apply
-// here too, or distill-written rank_score rows would use WS-2 weights while
-// preparation uses parity weights — inconsistent salience semantics.
-outcomeWeightEnabled) {
-    try {
-        const parsedRef = parseRefInput(ref);
-        const salienceResult = scoreEncodingSalience({
-            body,
-            type: parsedRef.type,
-            existingRefVocabulary,
-            revisionCount: 0, // a freshly distilled output IS a first encounter
-        });
-        withStateDb((stateDb) => {
-            const vector = computeSalience({
-                ref,
-                type: parsedRef.type,
-                retrievalFreq: 0,
-                encodingSalience: salienceResult.score,
-                outcomeWeightEnabled,
-            });
-            upsertAssetSalience(stateDb, ref, vector);
-        });
-    }
-    catch {
-        // Best-effort — scoring must never block proposal creation.
-    }
-}

package/dist/commands/improve/eval-cases.js

@@ -1,52 +0,0 @@
-// 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 fs from "node:fs";
-import path from "node:path";
-import { writeFileAtomic } from "../../core/common.js";
-import { getEvalCasesDir } from "../../core/paths.js";
-import { recordWrittenPath } from "../../core/write-provenance.js";
-export function writeEvalCase(stashDir, evalCase) {
-    const evalDir = getEvalCasesDir(stashDir);
-    fs.mkdirSync(evalDir, { recursive: true });
-    const fileName = `${evalCase.slug}.md`;
-    const filePath = path.join(evalDir, fileName);
-    const content = `---
-ref: ${evalCase.ref}
-failureReason: ${evalCase.failureReason}
-assetType: ${evalCase.assetType}
-rejectedAt: ${evalCase.rejectedAt}
-source: ${evalCase.source}
----
-
-# Eval Case: ${evalCase.ref}
-
-**Failure reason:** ${evalCase.failureReason}
-**Source:** ${evalCase.source}
-**Asset type:** ${evalCase.assetType}
-
-This case was automatically captured when a distillation or proposal was rejected.
-Use it as a regression test: future improve runs on this ref should not produce
-output that would be rejected for the same reason.
-`;
-    writeFileAtomic(filePath, content);
-    // itlackey/akm#890: journal it even though it now lands under `$STATE`,
-    // outside the stash's git repo — `result.writtenPaths` still reports it
-    // (as an absolute path; see describeRunWrittenPaths in improve.ts), and
-    // the auto-sync commit's own containment check already excludes anything
-    // outside the stash from what gets staged, so recording it here cannot
-    // cause it to be committed.
-    recordWrittenPath(filePath);
-    return filePath;
-}
-export function countEvalCases(stashDir) {
-    const evalDir = getEvalCasesDir(stashDir);
-    if (!fs.existsSync(evalDir))
-        return 0;
-    try {
-        return fs.readdirSync(evalDir).filter((f) => f.endsWith(".md")).length;
-    }
-    catch {
-        return 0;
-    }
-}

package/dist/commands/improve/memory/memory-contradiction-detect.js

@@ -1,291 +0,0 @@
-// 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/.
-/**
- * LLM-based contradiction-detection pass for derived memories (M-1 / #367).
- *
- * Runs BEFORE `analyzeMemoryCleanup` to populate `contradictedBy` frontmatter
- * edges so the existing `resolveFamilyContradictions` SCC resolver has real
- * input to work on. Without this pass the SCC resolver operates on a nearly
- * empty edge graph because no automated subsystem was previously generating
- * contradiction edges — the elegant Tarjan implementation in memory-improve.ts
- * had no input.
- *
- * # Algorithm
- *
- *   1. Collect all derived memories grouped by `parentRef` family.
- *   2. For each family, enumerate candidate pairs.
- *   3. For each pair, call the LLM to judge whether the two memories are in
- *      direct factual conflict.
- *   4. For confirmed contradictions, append a `contradictedBy` edge to the
- *      losing memory's frontmatter via `writeContradictEdge`
- *      (`./memory-belief.ts`).
- *
- * That last step used to call a private near-copy of `writeContradictEdge`
- * living in this file. The copy had drifted (#885): it read `contradictedBy`
- * with `Array.isArray` only, so a SCALAR edge — live data the indexer accepts
- * and lint never flags — read as "no edges" and was overwritten out of
- * existence; and it set `beliefState: "contradicted"` unconditionally,
- * promoting an `archived` memory back up (archived ranks BELOW contradicted).
- * Both behaviors had tests, but the tests exercised the shared primitive,
- * which nothing called — so they guarded dead code while the live path
- * carried the bugs.
- *
- * # LLM Feature Gate
- *
- * The pass is gated by the selected strategy's consolidate contradiction setting.
- * When the gate is disabled or no LLM is configured,
- * the pass is a no-op and `analyzeMemoryCleanup` proceeds with only manually
- * annotated edges.
- *
- * # References
- *
- * - Zep / Graphiti (arXiv:2501.13956): writes contradiction edges at detection time.
- * - ATMS (de Kleer 1986): assumption-based truth maintenance via edge propagation.
- * - mem0 contradiction probe (arXiv:2504.19413): pairwise LLM-judge pattern.
- */
-import fs from "node:fs";
-import path from "node:path";
-import contradictionJudgeTemplate from "../../../assets/prompts/contradiction-judge.md" with { type: "text" };
-import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
-import { parseEmbeddedJsonResponse } from "../../../core/parse.js";
-import { disposeLoweredExecutionDispatchLease } from "../../../integrations/agent/execution-lowering.js";
-import { callStructured, preflightStructuredLlmRunner } from "../../../llm/structured-call.js";
-import { resolveImproveLlmExecution } from "../execution.js";
-import { isDerivedMemory, memoryIdentityRef, resolveParentRef } from "./derived-ref.js";
-import { writeContradictEdge } from "./memory-belief.js";
-// ── Constants ────────────────────────────────────────────────────────────────
-/**
- * Minimum confidence required to write a contradiction edge. Below this
- * threshold the LLM may be flagging topic-overlap rather than genuine logical
- * exclusivity (investigation 2026-06-18).
- */
-const CONTRADICT_CONFIDENCE_THRESHOLD = 0.92;
-/**
- * Truncation limit for memory body content sent to the LLM judge.
- * Keeps prompts compact while preserving the key factual claims.
- */
-const BODY_TRUNCATION = 800;
-// ── Prompt builder ────────────────────────────────────────────────────────────
-function buildContradictionJudgePrompt(a, b) {
-    return contradictionJudgeTemplate
-        .replace("{{A_REF}}", a.ref)
-        .replace("{{A_DESCRIPTION}}", a.description || "(none)")
-        .replace("{{A_BODY}}", a.body.slice(0, BODY_TRUNCATION))
-        .replace("{{B_REF}}", b.ref)
-        .replace("{{B_DESCRIPTION}}", b.description || "(none)")
-        .replace("{{B_BODY}}", b.body.slice(0, BODY_TRUNCATION));
-}
-// ── Filesystem helpers ────────────────────────────────────────────────────────
-function* walkMarkdownFilesLocal(root) {
-    if (!fs.existsSync(root))
-        return;
-    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-        const full = path.join(root, entry.name);
-        if (entry.isDirectory())
-            yield* walkMarkdownFilesLocal(full);
-        else if (entry.isFile() && entry.name.endsWith(".md"))
-            yield full;
-    }
-}
-// Build the derived memory's own belief-edge IDENTITY ref from its file path.
-// Emits through the shared {@link memoryIdentityRef} so this — the former THIRD
-// hand-rolled copy of the identity-channel spelling — no longer diverges from
-// memory-improve's `refArray` (ref-grammar decision D-R3 identity-channel
-// exception, documented at `memoryIdentityRef`).
-function toMemoryRef(memoriesDir, filePath) {
-    const rel = path.relative(memoriesDir, filePath);
-    if (!rel || rel.startsWith(".."))
-        return undefined;
-    const name = rel.replace(/\\/g, "/").replace(/\.md$/i, "");
-    return memoryIdentityRef(name);
-}
-// ── Edge writing ─────────────────────────────────────────────────────────────
-/**
- * Deterministically pick, for a confirmed-contradiction pair, the LOSER memory
- * that receives the single directed `contradictedBy` edge (SCC-resolved to
- * `contradicted`) and the WINNER ref that survives as the current belief.
- *
- * A SINGLE directed edge is essential. Writing mutual A↔B edges forms a 2-cycle
- * that {@link resolveFamilyContradictions} collapses into one strongly-connected
- * SINK component and refreshes BOTH members back to active — erasing the
- * contradiction on every run (the self-erasing bug this fix removes).
- *
- * Direction = lexicographic ref order: the ref that sorts LATER is the loser.
- * This is a **total order** over the family's (distinct) refs, so the induced
- * edges are always acyclic — a family of any size resolves to a DAG with a
- * single sink, never a cycle that the resolver would refresh back to active.
- * It is also immutable across runs (unlike file mtime, which the resolver
- * bumps when it rewrites loser files), so detection is idempotent. Ref order
- * carries no recency meaning — no derived-memory writer sets a `createdAt`/
- * timestamp today — but the mechanism only needs a stable, acyclic direction;
- * eliminating worst-case self-erasure, not ranking by recency, is the goal.
- */
-function pickContradictionLoser(a, b) {
-    return a.ref < b.ref ? { loser: b, winnerRef: a.ref } : { loser: a, winnerRef: b.ref };
-}
-// ── Main entry point ──────────────────────────────────────────────────────────
-/**
- * Run the LLM-based contradiction-detection pass on derived memories in
- * `<stashDir>/memories/`. Writes `contradictedBy` frontmatter edges for
- * confirmed contradiction pairs so the subsequent `resolveFamilyContradictions`
- * SCC pass has edges to work on.
- *
- * @param stashDir - Root stash directory.
- * @param config   - Loaded AKM config (used to access LLM settings).
- * @param chat     - Optional test-only chat seam.
- */
-export async function detectAndWriteContradictions(stashDir, config, chat, strategy, resolvedRunner) {
-    const result = {
-        familiesExamined: 0,
-        pairsChecked: 0,
-        edgesWritten: 0,
-        warnings: [],
-    };
-    if (!(strategy?.processes?.consolidate?.contradictionDetection?.enabled ?? false))
-        return result;
-    const noticesByKey = new Map();
-    const resolvedExecution = resolvedRunner === undefined
-        ? resolveImproveLlmExecution({
-            config,
-            profile: strategy,
-            process: strategy?.processes?.consolidate,
-            processName: "memory-contradiction-detection",
-        })
-        : null;
-    for (const notice of resolvedExecution?.notices ?? [])
-        noticesByKey.set(JSON.stringify(notice), notice);
-    const contradictionRunner = resolvedRunner === null ? undefined : (resolvedRunner ?? resolvedExecution?.runner);
-    if (!contradictionRunner)
-        return result;
-    // Collect derived memories grouped by parent.
-    const memoriesDir = path.join(stashDir, "memories");
-    const byParent = new Map();
-    for (const filePath of walkMarkdownFilesLocal(memoriesDir)) {
-        let raw;
-        try {
-            raw = fs.readFileSync(filePath, "utf8");
-        }
-        catch {
-            continue;
-        }
-        const parsed = parseFrontmatter(raw);
-        const ref = toMemoryRef(memoriesDir, filePath);
-        if (!ref)
-            continue;
-        // Key the shared derived-ref helpers on the memory NAME (stash-relative, no
-        // extension) — the same key the consumer uses — so producer and consumer
-        // resolve the identical parent (R12). This intentionally widens the producer
-        // to honour `derivedFrom` and normalised `source:` values it previously
-        // dropped (pinned by derived-ref.test.ts).
-        const name = ref.slice("memory:".length);
-        if (!isDerivedMemory(name, parsed.data))
-            continue;
-        const parentRef = resolveParentRef(name, parsed.data);
-        if (!parentRef)
-            continue;
-        const entry = {
-            filePath,
-            ref,
-            parentRef,
-            body: parsed.content.trim(),
-            description: typeof parsed.data.description === "string" ? parsed.data.description : "",
-        };
-        const family = byParent.get(parentRef) ?? [];
-        family.push(entry);
-        byParent.set(parentRef, family);
-    }
-    const candidatePairs = [];
-    for (const [, family] of byParent) {
-        if (family.length < 2)
-            continue;
-        result.familiesExamined++;
-        for (let i = 0; i < family.length - 1; i++) {
-            for (let j = i + 1; j < family.length; j++) {
-                const a = family[i];
-                const b = family[j];
-                if (!a || !b)
-                    continue;
-                // Resolve the directed edge up front (independent of the judge — it is
-                // decided by lexicographic ref order). Skip when that single loser→winner
-                // edge already exists (no new information; avoids re-judging resolved
-                // pairs across runs).
-                //
-                const aParsed = parseFrontmatter(fs.readFileSync(a.filePath, "utf8"));
-                const bParsed = parseFrontmatter(fs.readFileSync(b.filePath, "utf8"));
-                const { loser, winnerRef } = pickContradictionLoser(a, b);
-                const loserData = loser === a ? aParsed.data : bParsed.data;
-                const loserCB = Array.isArray(loserData.contradictedBy) ? loserData.contradictedBy : [];
-                if (loserCB.includes(winnerRef))
-                    continue;
-                candidatePairs.push({ a, b, loser, winnerRef });
-            }
-        }
-    }
-    if (candidatePairs.length === 0) {
-        const notices = Object.freeze([...noticesByKey.values()]);
-        return notices.length > 0 ? { ...result, notices } : result;
-    }
-    const dispatchLease = await preflightStructuredLlmRunner(contradictionRunner);
-    try {
-        for (const { a, b, loser, winnerRef } of candidatePairs) {
-            const prompt = buildContradictionJudgePrompt(a, b);
-            const judgeResult = await callStructured({
-                feature: "memory_contradiction_detection",
-                akmConfig: config,
-                // Resolver-less key: the strategy decision IS the gate (default-off).
-                enabled: true,
-                runner: contradictionRunner,
-                lease: dispatchLease,
-                messages: [
-                    { role: "system", content: "Return only valid JSON. No prose." },
-                    { role: "user", content: prompt },
-                ],
-                ...(chat ? { request: { chat } } : {}),
-                onNotices: (notices) => {
-                    for (const notice of notices)
-                        noticesByKey.set(JSON.stringify(notice), notice);
-                },
-                parse: (raw) => raw ?? null,
-                // A transport throw used to escape the gated fn into the gate's
-                // catch and take the null fallback ("skip"); onError reproduces it.
-                onError: () => null,
-                fallback: null, // null means "skip" — gate disabled or LLM call failed.
-            });
-            result.pairsChecked++;
-            if (!judgeResult)
-                continue; // Feature gate disabled or LLM call failed.
-            let parsed = null;
-            try {
-                parsed = parseEmbeddedJsonResponse(judgeResult);
-            }
-            catch {
-                result.warnings.push(`Could not parse contradiction judge response for pair ${a.ref} / ${b.ref}`);
-                continue;
-            }
-            if (!parsed?.contradicts)
-                continue;
-            const confidence = typeof parsed.confidence === "number" ? parsed.confidence : 0;
-            if (confidence < CONTRADICT_CONFIDENCE_THRESHOLD) {
-                result.warnings.push(`Pair ${a.ref} / ${b.ref}: confidence ${confidence.toFixed(2)} below ${CONTRADICT_CONFIDENCE_THRESHOLD} threshold — skipped.`);
-                continue;
-            }
-            // Write a SINGLE directed contradiction edge: the losing (older) memory
-            // gets `contradictedBy` pointing to the winner. A mutual A↔B pair forms
-            // a 2-cycle that the SCC resolver refreshes back to active, erasing the
-            // contradiction every run (see pickContradictionLoser).
-            try {
-                const wrote = writeContradictEdge(loser.filePath, winnerRef);
-                result.edgesWritten += wrote ? 1 : 0;
-            }
-            catch (err) {
-                result.warnings.push(`Failed to write contradiction edge ${loser.ref} -> ${winnerRef}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-    }
-    finally {
-        disposeLoweredExecutionDispatchLease(dispatchLease);
-    }
-    const notices = Object.freeze([...noticesByKey.values()]);
-    return notices.length > 0 ? { ...result, notices } : result;
-}