akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

package/dist/commands/improve/distill/promote-memory.js

@@ -0,0 +1,229 @@
+// 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/.
+/**
+ * Memory→knowledge promotion branch for `akm distill`.
+ *
+ * This is an entire second command that used to be inlined inside `akmDistill`:
+ * when a `memory:*` ref is reinforced enough (per the deterministic stability
+ * heuristic in `distill-promotion-policy`), distill graduates it into a
+ * `knowledge:*` proposal instead of a lesson. The branch owns its own LLM
+ * contradiction-merge (mem0 ADD/UPDATE/NOOP), quality gate, proposal creation,
+ * and `distill_invoked` event emit.
+ *
+ * {@link promoteMemoryToKnowledge} returns the finished {@link AkmDistillResult}
+ * when the branch fired, or `null` when the ref is not a promotion candidate —
+ * in which case the caller falls through to the ordinary lesson/knowledge LLM
+ * path. Logic is byte-identical to the pre-extraction inline code.
+ */
+import fs from "node:fs";
+import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
+import { getDefaultLlmConfig } from "../../../core/config/config.js";
+import { ConfigError } from "../../../core/errors.js";
+import { appendEvent } from "../../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { isLlmFeatureEnabled } from "../../../llm/feature-gate.js";
+import { createProposal, isProposalSkipped } from "../../proposal/repository.js";
+import { assessMemoryKnowledgePromotionCandidate } from "../distill-promotion-policy.js";
+import { persistOutputEncodingSalience, runLessonQualityJudge, writeQualityRejection } from "./quality-gate.js";
+/**
+ * Run the memory→knowledge promotion branch. Returns the finished distill
+ * result when promotion fired (all paths terminal), or `null` when the ref is
+ * not a promotion candidate and the caller should continue to the ordinary
+ * lesson/knowledge distillation path.
+ */
+export async function promoteMemoryToKnowledge(ctx) {
+    const { targetKind, inputRef, assetContent, config, chat, stash, lookup, fetchSimilarLessonsFn, existingRefVocabulary, outcomeWeightEnabled, eligMeta, exclusionSetSize, filteredFeedbackCount, feedbackFullyFiltered, } = ctx;
+    const promotion = targetKind === "lesson"
+        ? null
+        : assessMemoryKnowledgePromotionCandidate({
+            inputRef,
+            assetContent,
+            feedbackEvents: ctx.filteredEvents.map((event) => ({
+                ...(event.metadata !== undefined ? { metadata: event.metadata } : {}),
+            })),
+        });
+    if (!(promotion?.promote && promotion.content && (targetKind === "knowledge" || targetKind === "auto"))) {
+        return null;
+    }
+    // D-1 / #369: When the destination knowledge file already exists, route
+    // through the LLM for contradiction resolution instead of silently
+    // overwriting. Follows mem0 ADD/UPDATE/DELETE/NOOP pattern (arXiv:2504.19413 §3.2)
+    // and A-MEM dynamic linking (arXiv:2502.12110).
+    let resolvedPromotionContent = promotion.content;
+    const existingKnowledgePath = await lookup(promotion.knowledgeRef);
+    const existingKnowledgeContent = existingKnowledgePath && fs.existsSync(existingKnowledgePath)
+        ? (() => {
+            try {
+                return fs.readFileSync(existingKnowledgePath, "utf8");
+            }
+            catch {
+                return null;
+            }
+        })()
+        : null;
+    if (existingKnowledgeContent && config && getDefaultLlmConfig(config)) {
+        // Existing content found: call LLM for contradiction-resolution merge.
+        const mergePrompt = [
+            "You are merging two versions of a knowledge document.",
+            "Existing content is already committed; new content comes from a memory distillation run.",
+            "Choose one of: ADD (combine both), UPDATE (replace existing with new), NOOP (keep existing unchanged).",
+            'Return ONLY valid JSON: {"action": "ADD"|"UPDATE"|"NOOP", "content": "<merged markdown if ADD/UPDATE, empty string if NOOP>"}',
+            "",
+            "## Existing knowledge content",
+            "```",
+            existingKnowledgeContent.slice(0, 3000),
+            "```",
+            "",
+            "## New content from distillation",
+            "```",
+            promotion.content.slice(0, 3000),
+            "```",
+        ].join("\n");
+        try {
+            const mergeLlm = getDefaultLlmConfig(config);
+            if (!mergeLlm) {
+                throw new ConfigError("LLM is not configured for distillation merge.", "LLM_NOT_CONFIGURED");
+            }
+            const mergeResponse = await chat(mergeLlm, [
+                { role: "system", content: "Return only valid JSON. No prose." },
+                { role: "user", content: mergePrompt },
+            ]);
+            const mergeResult = parseEmbeddedJsonResponse(mergeResponse);
+            if (mergeResult?.action === "NOOP") {
+                // Existing content is authoritative — no update needed.
+                appendEvent({
+                    eventType: "distill_invoked",
+                    ref: inputRef,
+                    metadata: {
+                        outcome: "skipped",
+                        lessonRef: promotion.knowledgeRef,
+                        message: "D-1: LLM resolved destination conflict as NOOP — existing content kept",
+                        ...eligMeta,
+                    },
+                });
+                return {
+                    schemaVersion: 1,
+                    ok: true,
+                    outcome: "skipped",
+                    inputRef,
+                    lessonRef: promotion.knowledgeRef,
+                    message: "Existing knowledge content unchanged (contradiction resolution: NOOP)",
+                };
+            }
+            if (mergeResult?.action && (mergeResult.action === "ADD" || mergeResult.action === "UPDATE")) {
+                if (mergeResult.content?.trim()) {
+                    resolvedPromotionContent = mergeResult.content;
+                }
+            }
+        }
+        catch {
+            // LLM merge failed — fall through with the original promotion content.
+            // The reviewer will see both versions in the proposal diff.
+        }
+    }
+    else if (existingKnowledgeContent && config && !getDefaultLlmConfig(config)) {
+        // No LLM configured: include existing content as context in the proposal
+        // so the reviewer can do the contradiction resolution manually.
+        resolvedPromotionContent = [
+            promotion.content,
+            "",
+            "---",
+            "<!-- D-1 / #369: Existing knowledge content is shown below for reviewer reference. -->",
+            "<!-- Review: decide whether to ADD (merge), UPDATE (replace), or NOOP (keep existing). -->",
+            "",
+            "## Existing content (for reviewer reference)",
+            "",
+            existingKnowledgeContent,
+        ].join("\n");
+    }
+    // Apply quality gate to fast-path knowledge promotion (Risk 4 fix).
+    // D-5 / #388: Three-band system — review_needed band queues to proposal
+    // queue with review_needed outcome rather than auto-rejecting.
+    let knowledgeJudgeConfidence;
+    if (isLlmFeatureEnabled(config, "lesson_quality_gate")) {
+        // D-4 / #390: retrieve top-3 similar lessons for dedup check in judge.
+        const similarLessons = await fetchSimilarLessonsFn(resolvedPromotionContent.slice(0, 500), 3);
+        const judgeResult = await runLessonQualityJudge(config, resolvedPromotionContent, assetContent ?? "", chat, similarLessons.length > 0 ? similarLessons : undefined);
+        if (!judgeResult.pass) {
+            if (judgeResult.reviewNeeded) {
+                // Uncertainty band (2.5–3.5): queue as review_needed instead of rejecting.
+                return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, { reviewNeeded: true }, ctx.eligibilitySource);
+            }
+            return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, {}, ctx.eligibilitySource);
+        }
+        // Normalize 1-5 judge score to [0, 1]. Only a real passing verdict reaches
+        // here (07 P0-2: the judge now fails CLOSED on no-LLM / timeout / parse
+        // failure, so those return pass:false and early-return above). The score>0
+        // guard defensively leaves confidence undefined for any non-positive score.
+        if (judgeResult.score > 0)
+            knowledgeJudgeConfidence = judgeResult.score / 5;
+    }
+    const knowledgeParsed = parseFrontmatter(resolvedPromotionContent);
+    const proposalResult = createProposal(stash, {
+        ref: promotion.knowledgeRef,
+        source: "distill",
+        ...(ctx.sourceRun !== undefined ? { sourceRun: ctx.sourceRun } : {}),
+        payload: {
+            content: resolvedPromotionContent,
+            ...(Object.keys(knowledgeParsed.data).length > 0 ? { frontmatter: knowledgeParsed.data } : {}),
+        },
+        ...(knowledgeJudgeConfidence !== undefined ? { confidence: knowledgeJudgeConfidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal.
+        ...(ctx.eligibilitySource ? { eligibilitySource: ctx.eligibilitySource } : {}),
+    }, ctx.proposalsCtx);
+    if (isProposalSkipped(proposalResult)) {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "skipped",
+                lessonRef: promotion.knowledgeRef,
+                message: proposalResult.message,
+                skipReason: proposalResult.reason,
+                ...eligMeta,
+            },
+        });
+        return {
+            schemaVersion: 1,
+            ok: true,
+            outcome: "skipped",
+            inputRef,
+            lessonRef: promotion.knowledgeRef,
+            message: proposalResult.message,
+        };
+    }
+    const proposal = proposalResult;
+    // G4: content-score the distilled OUTPUT so it carries a real encoding
+    // salience (encoding_source='content') from creation.
+    persistOutputEncodingSalience(promotion.knowledgeRef, resolvedPromotionContent, existingRefVocabulary, outcomeWeightEnabled);
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome: "queued",
+            lessonRef: promotion.knowledgeRef,
+            proposalRef: promotion.knowledgeRef,
+            proposalKind: "knowledge",
+            proposalId: proposal.id,
+            // R3: judge verdicts are longitudinally queryable, not just a one-shot
+            // proposal.confidence write (normalized 1–5 score / 5).
+            ...(knowledgeJudgeConfidence !== undefined ? { judgeConfidence: knowledgeJudgeConfidence } : {}),
+            ...(ctx.sourceRun !== undefined ? { sourceRun: ctx.sourceRun } : {}),
+            ...(exclusionSetSize > 0 ? { filteredFeedbackCount } : {}),
+            ...eligMeta,
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "queued",
+        inputRef,
+        lessonRef: promotion.knowledgeRef,
+        proposalRef: promotion.knowledgeRef,
+        proposalKind: "knowledge",
+        proposalId: proposal.id,
+        proposal,
+        ...(exclusionSetSize > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+    };
+}

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

@@ -0,0 +1,236 @@
+// 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 { parseAssetRef } from "../../../core/asset/asset-ref.js";
+import { timestampForFilename } from "../../../core/common.js";
+import { getDefaultLlmConfig } from "../../../core/config/config.js";
+import { appendEvent } from "../../../core/events.js";
+import { withStateDb } from "../../../core/state-db.js";
+import { parseEmbeddedJsonResponse } from "../../../llm/client.js";
+import { akmSearch } from "../../read/search.js";
+import { scoreEncodingSalience } from "../encoding-salience.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");
+}
+/**
+ * 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).
+ * Gated by the flag name `lesson_quality_gate` (or its alias
+ * `proposal_quality_gate`) via {@link isLlmFeatureEnabled} — which reads
+ * `profiles.improve.default.processes.distill.qualityGate.enabled` (and the
+ * corresponding `.reflect.qualityGate.enabled` for proposals).
+ *
+ * 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, 
+/** D-4 / #390: top-3 similar existing lessons for dedup check. */
+similarLessons) {
+    const llmConfig = getDefaultLlmConfig(config);
+    if (!llmConfig) {
+        return { pass: false, score: -1, reason: "no LLM configured — cannot judge, failing closed" };
+    }
+    const judgeLlmConfig = llmConfig.judgeModel ? { ...llmConfig, model: llmConfig.judgeModel } : llmConfig;
+    const JUDGE_TIMEOUT_MS = 8_000;
+    try {
+        const raw = await Promise.race([
+            chat(judgeLlmConfig, [
+                { role: "system", content: "Return only valid JSON. No prose." },
+                { role: "user", content: buildJudgePrompt(lessonContent, sourceContent, similarLessons) },
+            ]),
+            new Promise((_, reject) => setTimeout(() => reject(new Error("judge timeout")), JUDGE_TIMEOUT_MS)),
+        ]);
+        const parsed = parseEmbeddedJsonResponse(raw);
+        if (!parsed || typeof parsed.score !== "number") {
+            return { pass: false, score: -1, reason: "judge parse failed — cannot judge, failing closed" };
+        }
+        // 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) {
+            // Uncertainty band: treat as failed for auto-queuing but flag for review.
+            return { pass: false, score, reason, reviewNeeded: true };
+        }
+        return { pass: false, score, reason };
+    }
+    catch {
+        return { pass: false, score: -1, reason: "judge timeout/error — cannot judge, failing closed" };
+    }
+}
+// ── Quality-rejection helper ─────────────────────────────────────────────────
+/**
+ * Write a rejected lesson to `.akm/distill-rejected/`, 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 lessonRef - 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.
+ */
+export function writeQualityRejection(stash, inputRef, lessonRef, content, score, reason, extraMeta = {}, eligibilitySource) {
+    // D-5 / #388: reviewNeeded flag selects "review_needed" vs "quality_rejected" outcome.
+    const outcome = extraMeta.reviewNeeded ? "review_needed" : "quality_rejected";
+    const rejectDir = path.join(stash, ".akm", "distill-rejected");
+    fs.mkdirSync(rejectDir, { recursive: true });
+    const ts = timestampForFilename();
+    fs.writeFileSync(path.join(rejectDir, `${ts}-${lessonRef}.md`), `---\nscore: ${score}\nreason: ${reason}\noutcome: ${outcome}\n---\n\n${content}`, "utf8");
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome,
+            lessonRef,
+            score,
+            reason,
+            ...extraMeta,
+            // Attribution tagging: stamp the eligibility lane so distill_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(eligibilitySource ? { eligibilitySource } : {}),
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome,
+        inputRef,
+        lessonRef,
+        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 = parseAssetRef(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/distill-guards.js

@@ -0,0 +1,127 @@
+// 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/.
+/**
+ * WS-3b distill-stage guards.
+ *
+ * **CLS interleaving (step 9)**
+ *   distill/memoryInference prompts include embedding-retrieved adjacent
+ *   lessons/knowledge so the pipeline doesn't overwrite prior generalizations.
+ *
+ * **Distill→source fidelity (step 10)**
+ *   After a distill proposal, check it against cited source memories; a
+ *   contradiction flag routes to human review.
+ *
+ * @module distill-guards
+ */
+// ── CLS adjacent lesson context (step 9) ─────────────────────────────────────
+/** Default number of adjacent lessons/knowledge for CLS interleaving. */
+export const DEFAULT_CLS_ADJACENT_COUNT = 3;
+/**
+ * Build a CLS (Complementary Learning System) context snippet for injection
+ * into distill/memoryInference prompts.
+ *
+ * Given a list of embedding-retrieved adjacent lessons/knowledge, formats them
+ * as a markdown section to append to the prompt so the LLM avoids overwriting
+ * prior generalizations.
+ *
+ * Returns an empty string when CLS is disabled or no adjacent items are found.
+ *
+ * @param adjacentItems - Top-N adjacent lessons/knowledge retrieved by embedding.
+ * @param config - CLS config.
+ */
+export function buildClsContext(adjacentItems, config) {
+    if (!config.enabled || adjacentItems.length === 0)
+        return "";
+    const lines = [
+        "",
+        "## Existing adjacent lessons / knowledge (CLS context)",
+        "The following are semantically related entries already in the stash.",
+        "Your proposal MUST NOT contradict or silently overwrite these — if you",
+        "disagree with one, flag it as contradicted (do not ignore it).",
+        "",
+    ];
+    for (const item of adjacentItems) {
+        lines.push(`### ${item.ref}`);
+        // Truncate to 400 chars to keep the prompt size reasonable.
+        lines.push(item.content.trim().slice(0, 400));
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/**
+ * Check a distill proposal against its cited source memories for contradictions.
+ *
+ * Uses a simple heuristic: looks for explicit negation of key claims in the
+ * proposal body that appear in the source bodies. A full LLM-based
+ * contradiction check is expensive (one LLM call per proposal); this cheap
+ * heuristic catches the most obvious cases and flags them for human review.
+ *
+ * When `fidelityCheck.enabled` is false, returns `{ contradictionDetected: false }`
+ * immediately (no work done).
+ *
+ * @param proposalBody - The stripped body of the distill proposal.
+ * @param sourceBodies - The stripped bodies of the cited source memories.
+ * @param config - Fidelity check config.
+ */
+export function checkDistillFidelity(proposalBody, sourceBodies, config) {
+    if (!config.enabled || sourceBodies.length === 0) {
+        return { contradictionDetected: false };
+    }
+    // Heuristic: detect explicit negation of "never" / "always" / "must" claims.
+    // A proposal that says "always X" while the source says "never X" (or vice
+    // versa) is a clear contradiction worth flagging.
+    //
+    // This is intentionally conservative: it only flags when both the proposal
+    // AND the source contain the opposing polarity of the same key term. False
+    // negatives (missed contradictions) are preferred over false positives
+    // (blocking valid proposals) since the consequence of a false positive is
+    // a human review request, while the cost of a false negative is a slightly
+    // degraded stash.
+    const proposalLow = proposalBody.toLowerCase();
+    // Extract "always/never/must/must not" claims from the proposal.
+    const strongClaims = extractStrongClaims(proposalLow);
+    if (strongClaims.length === 0)
+        return { contradictionDetected: false };
+    for (const sourceBody of sourceBodies) {
+        const sourceLow = sourceBody.toLowerCase();
+        for (const { polarity, term } of strongClaims) {
+            const oppositePolarity = polarity === "positive" ? "negative" : "positive";
+            const sourceHasOpposite = hasStrongClaim(sourceLow, term, oppositePolarity);
+            if (sourceHasOpposite) {
+                return {
+                    contradictionDetected: true,
+                    reason: `Proposal makes a ${polarity} strong claim about "${term}" that conflicts with an opposing claim in a cited source. Route to human review.`,
+                };
+            }
+        }
+    }
+    // Also flag proposals whose source_refs are empty (broken provenance).
+    // This is a degradation signal, not a contradiction, but worth surfacing.
+    return { contradictionDetected: false };
+}
+function extractStrongClaims(text) {
+    const claims = [];
+    // Match "always <term>", "never <term>", "must <term>", "must not <term>".
+    const patterns = [
+        { polarity: "positive", re: /\b(?:always|must)\s+(\w+)/g },
+        { polarity: "negative", re: /\b(?:never|must\s+not|should\s+not)\s+(\w+)/g },
+    ];
+    for (const { polarity, re } of patterns) {
+        re.lastIndex = 0;
+        let m = re.exec(text);
+        while (m !== null) {
+            const term = m[1];
+            if (term && term.length > 2)
+                claims.push({ polarity, term });
+            m = re.exec(text);
+        }
+    }
+    return claims;
+}
+function hasStrongClaim(text, term, polarity) {
+    if (polarity === "positive") {
+        return /\b(?:always|must)\s/.test(text) && text.includes(term);
+    }
+    return /\b(?:never|must\s+not|should\s+not)\s/.test(text) && text.includes(term);
+}