akm-cli 0.9.0-beta.2 → 0.9.0-beta.27

package/dist/commands/improve/recombine.js

@@ -0,0 +1,488 @@
+// 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/.
+/**
+ * #609 — recombine / synthesize pass.
+ *
+ * A whole-corpus synthesis stage that runs AFTER consolidation and is OPT-IN
+ * (default disabled via `IMPROVE_PROCESS_DEFAULTS.recombine`). It clusters
+ * memories by RELATEDNESS (shared tags / graph entities — NEVER embedding
+ * similarity), issues ONE bounded LLM call per cluster to induce a single
+ * cross-episodic generalization, and emits the result as a NORMAL pending
+ * proposal with frontmatter `type: hypothesis` through the existing proposal
+ * queue + quality gate.
+ *
+ * Two-pass contract: the first pass ONLY ever emits `type: hypothesis`
+ * proposals — never a `type: lesson`. Promotion to a lesson happens on a later
+ * confirmation run once the same generalization has been re-induced
+ * `confirmThreshold` times (#625). The confirmation count is persisted in the
+ * `recombine_hypotheses` state.db table (migration 014), keyed by the
+ * deterministic `deriveRecombineLessonRef` value so re-induction of the SAME
+ * member-set maps back to the SAME row. When the count reaches the threshold,
+ * the run emits ONE `type: lesson` promotion proposal through the SAME proposal
+ * queue + quality gate (createProposal + validateProposalFrontmatter), NEVER a
+ * direct stash write, then marks the row promoted (resetting its count) so it is
+ * not re-promoted on every subsequent run. Hypotheses NOT re-induced in a run
+ * have their consecutive streak reset (decay-to-zero).
+ *
+ * NAMESPACE note: the ref stays `lesson:recombined/<slug>-<hash>` for BOTH
+ * passes. The ref is the promotion TARGET asset (a lesson in both the hypothesis
+ * and promoted states), so re-induction must map to the same ref and the ref
+ * cannot encode the proposal type. The hypothesis-vs-lesson distinction is
+ * carried ONLY by the proposal frontmatter `type` field. On promotion the prior
+ * pending `type: hypothesis` proposal for that ref is superseded (rejected) so
+ * the queue never shows two proposals for one ref.
+ *
+ * A justified null (the LLM determines no defensible generalization exists) is
+ * an acceptable outcome: it produces no proposal and records a
+ * `recombine_invoked` event with `outcome: 'null_returned'`.
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import recombineSystemPrompt from "../../assets/prompts/recombine-system.md" with { type: "text" };
+import { parseFrontmatter } from "../../core/asset/frontmatter.js";
+import { resolveStashDir } from "../../core/common.js";
+import { getDefaultLlmConfig, loadConfig } from "../../core/config/config.js";
+import { appendEvent } from "../../core/events.js";
+import { parseEmbeddedJsonResponse } from "../../core/parse.js";
+import { decayUnseenRecombineHypotheses, getRecombineHypothesis, getStateDbPath, markRecombineHypothesisPromoted, openStateDatabase, recordRecombineInduction, } from "../../core/state-db.js";
+import { warn } from "../../core/warn.js";
+import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
+import { resolveImproveProcessRunnerFromProfile, runnerIsLlm } from "../../integrations/agent/runner.js";
+import { chatCompletion } from "../../llm/client.js";
+import { validateProposalFrontmatter } from "../proposal/validators/proposal-quality-validators.js";
+import { archiveProposal, createProposal, isProposalSkipped, listProposals } from "../proposal/validators/proposals.js";
+import { isConsolidationEligibleMemoryName } from "./consolidate.js";
+const RECOMBINE_SYSTEM_PROMPT = recombineSystemPrompt;
+const DEFAULT_MIN_CLUSTER_SIZE = 3;
+const DEFAULT_MAX_CLUSTERS_PER_RUN = 5;
+const DEFAULT_RELATEDNESS_SOURCE = "tags";
+/** #625 — re-induction count required before a hypothesis promotes to a lesson. */
+const DEFAULT_CONFIRM_THRESHOLD = 2;
+// ── Clustering by relatedness (NOT similarity) ────────────────────────────────
+/**
+ * Build relatedness clusters from the memory pool. Clustering is driven purely
+ * by shared tags / graph entities — it MUST NOT use embedding similarity, so
+ * textually near-identical memories that share no relatedness signal never
+ * cluster together.
+ *
+ * For `relatednessSource`:
+ *   - `"tags"`  — group by each frontmatter tag.
+ *   - `"graph"` — group by shared `graph_file_entities.entity_norm`; falls back
+ *                 to tags when the graph table is empty (fail-open).
+ *   - `"both"`  — union of the tag and entity grouping keys.
+ *
+ * A cluster is a signal whose member set is >= `minClusterSize`. Overlapping
+ * clusters are de-duplicated by member-set identity, and the result is capped
+ * to `maxClustersPerRun` by member-count descending.
+ */
+export function buildRelatednessClusters(entries, opts) {
+    // Only consolidation-eligible memories participate (exclude `.derived`).
+    const memories = entries.filter((e) => e.entry.type === "memory" && isConsolidationEligibleMemoryName(e.entry.name));
+    // signal -> member entries
+    const groups = new Map();
+    const add = (signal, entry) => {
+        const key = signal.trim();
+        if (!key)
+            return;
+        const list = groups.get(key);
+        if (list) {
+            if (!list.includes(entry))
+                list.push(entry);
+        }
+        else {
+            groups.set(key, [entry]);
+        }
+    };
+    const useTags = opts.relatednessSource === "tags" || opts.relatednessSource === "both";
+    // Graph relatedness falls open to tags when no entities are available.
+    const hasEntities = !!opts.entityByEntryId && opts.entityByEntryId.size > 0;
+    const useGraph = (opts.relatednessSource === "graph" || opts.relatednessSource === "both") && hasEntities;
+    const tagsFallback = !useTags && opts.relatednessSource === "graph" && !hasEntities;
+    for (const entry of memories) {
+        if (useTags || tagsFallback) {
+            for (const tag of entry.entry.tags ?? [])
+                add(`tag:${tag}`, entry);
+        }
+        if (useGraph && opts.entityByEntryId) {
+            for (const ent of opts.entityByEntryId.get(entry.id) ?? [])
+                add(`entity:${ent}`, entry);
+        }
+    }
+    // Keep only groups at or above the minimum cluster size.
+    let clusters = [];
+    for (const [signature, members] of groups) {
+        if (members.length >= opts.minClusterSize)
+            clusters.push({ signature, members });
+    }
+    // De-duplicate clusters that share the exact same member set (e.g. a tag and
+    // an entity that co-occur on the same trio). Keep the first by signature.
+    const seenMemberKeys = new Set();
+    clusters = clusters.filter((c) => {
+        const memberKey = c.members
+            .map((m) => m.id)
+            .sort((a, b) => a - b)
+            .join(",");
+        if (seenMemberKeys.has(memberKey))
+            return false;
+        seenMemberKeys.add(memberKey);
+        return true;
+    });
+    // Cap to maxClustersPerRun, largest clusters first (deterministic tiebreak).
+    clusters.sort((a, b) => b.members.length - a.members.length || a.signature.localeCompare(b.signature));
+    return clusters.slice(0, Math.max(0, opts.maxClustersPerRun));
+}
+// ── Prompt + ref derivation ───────────────────────────────────────────────────
+/** Read a memory body (frontmatter stripped) for the cluster prompt. */
+function readBody(entry) {
+    try {
+        const raw = fs.readFileSync(entry.filePath, "utf8");
+        return parseFrontmatter(raw).content.trim();
+    }
+    catch {
+        return "";
+    }
+}
+/** Assemble the per-cluster user prompt fed to the recombine LLM. */
+export function buildClusterPrompt(cluster) {
+    const lines = [
+        `Shared signal: ${cluster.signature}`,
+        `Cluster of ${cluster.members.length} related memories:`,
+        "",
+    ];
+    for (const m of cluster.members) {
+        lines.push(`[memory:${m.entry.name}]`);
+        if (m.entry.description)
+            lines.push(`Description: ${m.entry.description}`);
+        const body = readBody(m);
+        if (body)
+            lines.push(body);
+        lines.push("");
+    }
+    lines.push("Induce ONE cross-episodic generalization these memories support, or return an explicit null if none is defensible.");
+    return lines.join("\n");
+}
+/**
+ * Stable lesson ref for a cluster. The hash of the sorted member refs keeps the
+ * ref deterministic across runs (so re-induction maps to the same ref + the
+ * content-hash dedup in createProposal suppresses queue churn).
+ */
+export function deriveRecombineLessonRef(cluster) {
+    const slug = cluster.signature
+        .replace(/^(tag|entity):/, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    const memberKey = recombineMemberKey(cluster);
+    const hash = createHash("sha256").update(memberKey, "utf8").digest("hex").slice(0, 8);
+    return `lesson:recombined/${slug || "cluster"}-${hash}`;
+}
+/**
+ * The membership fingerprint of a cluster: its member entryKeys sorted and
+ * joined. Single source of truth shared by {@link deriveRecombineLessonRef}'s
+ * hash and the `recombine_hypotheses.member_key` column, so the table key and
+ * the ref hash always derive from the SAME member set. Adding/removing one
+ * memory yields a different fingerprint → a different ref → a fresh row (the
+ * old streak is correctly NOT inherited).
+ */
+export function recombineMemberKey(cluster) {
+    return cluster.members
+        .map((m) => m.entryKey)
+        .sort()
+        .join("|");
+}
+/** Parse the raw LLM output into a generalization, or `null` for the justified-null path. */
+function parseGeneralization(raw) {
+    if (raw === null)
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "null")
+        return null;
+    const parsed = parseEmbeddedJsonResponse(trimmed);
+    if (parsed === undefined || parsed === null)
+        return null;
+    if (typeof parsed !== "object")
+        return null;
+    const obj = parsed;
+    const description = typeof obj.description === "string" ? obj.description : "";
+    const body = typeof obj.body === "string" ? obj.body : "";
+    const when_to_use = typeof obj.when_to_use === "string" ? obj.when_to_use : undefined;
+    // An empty object / all-empty fields is treated as a justified null.
+    if (!description && !body)
+        return null;
+    return { description, body, ...(when_to_use ? { when_to_use } : {}) };
+}
+/**
+ * Resolve the production LLM seam from the active improve profile. Returns a
+ * `RecombineLlmFn` that issues one bounded chatCompletion per call, or
+ * `undefined` when no LLM is configured (the pass then makes no calls).
+ */
+function resolveProductionLlmFn(config, signal) {
+    const recombineProcess = config.profiles?.improve?.default?.processes?.recombine;
+    const runnerSpec = resolveImproveProcessRunnerFromProfile(recombineProcess, config);
+    const llmConfig = runnerSpec && runnerIsLlm(runnerSpec) ? runnerSpec.connection : getDefaultLlmConfig(config);
+    if (!llmConfig)
+        return undefined;
+    return async (clusterPrompt) => {
+        const messages = [
+            { role: "system", content: RECOMBINE_SYSTEM_PROMPT },
+            { role: "user", content: clusterPrompt },
+        ];
+        try {
+            return await chatCompletion(llmConfig, messages, { signal, enableThinking: false });
+        }
+        catch (e) {
+            warn(`[recombine] LLM call failed: ${String(e)}`);
+            return null;
+        }
+    };
+}
+// ── Main entry point ───────────────────────────────────────────────────────────
+export async function akmRecombine(opts) {
+    const startMs = Date.now();
+    const config = opts.config ?? loadConfig();
+    const stashDir = opts.stashDir ?? resolveStashDir();
+    const sourceRun = opts.sourceRun ?? `recombine-${startMs}`;
+    const eligibilitySource = opts.eligibilitySource ?? "recombine";
+    const minClusterSize = opts.minClusterSize ?? DEFAULT_MIN_CLUSTER_SIZE;
+    const maxClustersPerRun = opts.maxClustersPerRun ?? DEFAULT_MAX_CLUSTERS_PER_RUN;
+    const relatednessSource = opts.relatednessSource ?? DEFAULT_RELATEDNESS_SOURCE;
+    const confirmThreshold = opts.confirmThreshold ?? DEFAULT_CONFIRM_THRESHOLD;
+    const warnings = [];
+    const finish = (over) => ({
+        schemaVersion: 1,
+        ok: true,
+        clustersFormed: 0,
+        proposalsEmitted: 0,
+        lessonsPromoted: 0,
+        nullsReturned: 0,
+        durationMs: Date.now() - startMs,
+        warnings,
+        ...over,
+    });
+    // Budget guard: an already-aborted signal short-circuits before any LLM call.
+    if (opts.signal?.aborted) {
+        return finish({ ok: false, warnings: [...warnings, "aborted-before-start"] });
+    }
+    // Load the memory pool + (optionally) graph entities from the index.
+    let entries = [];
+    let entityByEntryId;
+    let db;
+    try {
+        db = openExistingDatabase();
+        entries = getAllEntries(db, "memory");
+        if (relatednessSource === "graph" || relatednessSource === "both") {
+            try {
+                entityByEntryId = getEntitiesByEntryIds(db, entries.map((e) => e.id));
+            }
+            catch {
+                // Fail open to tag relatedness.
+                entityByEntryId = undefined;
+            }
+        }
+    }
+    catch (e) {
+        warnings.push(`recombine: failed to open index — ${String(e)}`);
+        return finish({ ok: false });
+    }
+    finally {
+        if (db)
+            closeDatabase(db);
+    }
+    const clusters = buildRelatednessClusters(entries, {
+        minClusterSize,
+        maxClustersPerRun,
+        relatednessSource,
+        ...(entityByEntryId ? { entityByEntryId } : {}),
+    });
+    let clustersFormed = 0;
+    let proposalsEmitted = 0;
+    let lessonsPromoted = 0;
+    let nullsReturned = 0;
+    const llmFn = opts.recombineLlmFn ?? resolveProductionLlmFn(config, opts.signal);
+    if (!llmFn) {
+        warnings.push("recombine: no LLM configured — skipping");
+        return finish({ clustersFormed: 0 });
+    }
+    // #625 — open the confirmation-count store once per run via the ctx seam,
+    // reusing a long-lived ctx.db handle when the caller provided one (mirrors
+    // proposals.ts). Only handles WE opened are closed in the finally below.
+    const ownStateDb = opts.ctx?.db ? undefined : openStateDatabase(opts.ctx?.dbPath ?? getStateDbPath());
+    const stateDb = opts.ctx?.db ?? ownStateDb;
+    // Refs re-induced (defensible generalization passed the quality gate) THIS
+    // run — everything else is decayed after the loop.
+    const seenThisRun = new Set();
+    try {
+        for (const cluster of clusters) {
+            if (opts.signal?.aborted) {
+                warnings.push("aborted-mid-run");
+                break;
+            }
+            clustersFormed += 1;
+            const prompt = buildClusterPrompt(cluster);
+            const raw = await llmFn(prompt);
+            const generalization = parseGeneralization(raw);
+            if (!generalization) {
+                nullsReturned += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: deriveRecombineLessonRef(cluster),
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "null_returned",
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            const lessonRef = deriveRecombineLessonRef(cluster);
+            const sourceRefs = cluster.members.map((m) => `memory:${m.entry.name}`);
+            // Quality gate (always-run): the frontmatter description must be present
+            // and non-truncated. This runs BEFORE createProposal on BOTH the
+            // hypothesis and the promotion paths — never bypassed.
+            const fmCheck = validateProposalFrontmatter({ description: generalization.description });
+            if (!fmCheck.ok) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "quality_rejected",
+                        reason: fmCheck.reason,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            // A defensible generalization was produced this run — record it so it is
+            // NOT decayed by the unseen sweep below.
+            seenThisRun.add(lessonRef);
+            // #625 — record the re-induction and read the prior promotion state. The
+            // member key and the ref hash derive from the SAME member set, so
+            // re-induction of an identical cluster maps back to the same row.
+            const nowIso = new Date().toISOString();
+            const priorRow = stateDb ? getRecombineHypothesis(stateDb, lessonRef) : undefined;
+            const alreadyPromoted = priorRow?.promoted_at != null;
+            const count = stateDb
+                ? recordRecombineInduction(stateDb, {
+                    hypothesisRef: lessonRef,
+                    signature: cluster.signature,
+                    memberKey: recombineMemberKey(cluster),
+                    seenAt: nowIso,
+                    run: sourceRun,
+                })
+                : 0;
+            // Promote to a `type: lesson` proposal when the confirmation streak
+            // reaches the threshold AND the hypothesis has not already been promoted.
+            const promote = stateDb != null && !alreadyPromoted && count >= confirmThreshold;
+            const proposalType = promote ? "lesson" : "hypothesis";
+            const frontmatter = {
+                type: proposalType,
+                description: generalization.description,
+                ...(generalization.when_to_use ? { when_to_use: generalization.when_to_use } : {}),
+                source_refs: sourceRefs,
+            };
+            const content = assembleContent(frontmatter, generalization.body);
+            if (promote && stateDb) {
+                // Supersede the prior pending `type: hypothesis` proposal for this ref so
+                // the queue never shows two proposals for one ref. The promoted lesson
+                // proposal has different content (type changed), so content-hash dedup
+                // would otherwise let both co-exist.
+                for (const stale of listProposals(stashDir, { status: "pending", ref: lessonRef }, opts.ctx)) {
+                    if (stale.source === "recombine") {
+                        archiveProposal(stashDir, stale.id, "rejected", "superseded by recombine lesson promotion", opts.ctx);
+                    }
+                }
+            }
+            const proposalResult = createProposal(stashDir, {
+                ref: lessonRef,
+                source: "recombine",
+                sourceRun,
+                payload: { content, frontmatter: { description: generalization.description } },
+                eligibilitySource,
+                // The promotion is a distinct asset (lesson) for the same ref; force
+                // past the duplicate-pending guard (the stale hypothesis was just
+                // superseded, but force keeps the path robust to ordering).
+                ...(promote ? { force: true } : {}),
+            }, opts.ctx);
+            if (isProposalSkipped(proposalResult)) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "skipped",
+                        skipReason: proposalResult.reason,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+                continue;
+            }
+            if (promote && stateDb) {
+                markRecombineHypothesisPromoted(stateDb, lessonRef, nowIso);
+                lessonsPromoted += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "promoted",
+                        proposalId: proposalResult.id,
+                        confirmationCount: count,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+            }
+            else {
+                proposalsEmitted += 1;
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    ref: lessonRef,
+                    metadata: {
+                        signal: cluster.signature,
+                        memberCount: cluster.members.length,
+                        outcome: "queued",
+                        proposalId: proposalResult.id,
+                        confirmationCount: count,
+                        sourceRun,
+                    },
+                }, opts.ctx);
+            }
+        }
+        // #625 — decay hypotheses NOT re-induced this run (reset their consecutive
+        // streak) so confirmation is per-consecutive-run and conservative (AC4).
+        if (stateDb) {
+            const decayedCount = decayUnseenRecombineHypotheses(stateDb, sourceRun, [...seenThisRun]);
+            if (decayedCount > 0) {
+                appendEvent({
+                    eventType: "recombine_invoked",
+                    metadata: { outcome: "decayed", decayedCount, sourceRun },
+                }, opts.ctx);
+            }
+        }
+    }
+    finally {
+        if (ownStateDb)
+            ownStateDb.close();
+    }
+    return finish({ clustersFormed, proposalsEmitted, lessonsPromoted, nullsReturned });
+}
+/** Serialize frontmatter + body into a markdown asset string. */
+function assembleContent(frontmatter, body) {
+    const lines = ["---"];
+    for (const [key, value] of Object.entries(frontmatter)) {
+        if (Array.isArray(value)) {
+            lines.push(`${key}: [${value.map((v) => JSON.stringify(v)).join(", ")}]`);
+        }
+        else {
+            lines.push(`${key}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+        }
+    }
+    lines.push("---", "", body, "");
+    return lines.join("\n");
+}

package/dist/commands/improve/reflect.js

@@ -46,6 +46,7 @@ import { baseFailureFields, enoentHintMessage, isEnoentFailure, loadAgentConfigF
 import { checkReflectSize } from "../proposal/validators/proposal-quality-validators.js";
 import { createProposal, isProposalSkipped, listProposals, } from "../proposal/validators/proposals.js";
 import { deriveLessonRef, runLessonQualityJudge } from "./distill.js";
+import { classifyReflectChange } from "./reflect-noise.js";
 const MAX_FEEDBACK_LINES = 10;
 const MAX_GLOBAL_FEEDBACK_LINES = 20;
 /**
@@ -382,6 +383,25 @@ function splitFrontmatter(raw) {
         return { fmText: null, body: raw };
     return { fmText: m[1], body: m[2] };
 }
+/**
+ * Strip an LLM-appended duplicate frontmatter block from a body string.
+ *
+ * When the LLM echoes the original source file verbatim after its rewrite,
+ * the resulting body contains a second `---...---` YAML block. We detect it
+ * by requiring BOTH a balanced fence (opening + closing `---`) AND YAML-like
+ * `key: value` content inside, so legitimate Markdown thematic breaks and
+ * code-fence examples are never truncated.
+ */
+function stripAppendedFrontmatter(body) {
+    const fencePattern = /\n---\r?\n([\s\S]*?)\n---\r?\n/;
+    const match = body.match(fencePattern);
+    if (!match)
+        return body;
+    // Only strip when the captured block looks like YAML frontmatter.
+    if (!/^\w[\w-]*:/m.test(match[1]))
+        return body;
+    return body.slice(0, body.indexOf(match[0])).replace(/\s+$/, "");
+}
 /**
  * Reflect post-processor — enforces the safety rails described at the top of
  * this file:
@@ -448,7 +468,7 @@ function sanitizeReflectPayload(payload, sourceContent, targetRef) {
             mergedFm[field] = sourceFm[field];
         }
     }
-    const cleanedBody = rawLlmBody.replace(/^\s+/, "");
+    const cleanedBody = stripAppendedFrontmatter(rawLlmBody.replace(/^\s+/, ""));
     // Size guard — only when source body is meaningfully large. The pure
     // predicate lives in `core/proposal-quality-validators` so the same check
     // also runs inside `runProposalValidators` on `proposal accept`.
@@ -584,6 +604,9 @@ export async function akmReflect(options = {}) {
         metadata: {
             ...(options.task ? { task: options.task } : {}),
             ...(options.profile ? { profile: options.profile } : {}),
+            // Attribution tagging: stamp the eligibility lane so reflect_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
         },
     });
     // Fix #3 (observability 0.8.0): every failure path below MUST emit
@@ -1138,6 +1161,30 @@ export async function akmReflect(options = {}) {
         content: sanitizeOutcome.content,
         ...(sanitizeOutcome.frontmatter ? { frontmatter: sanitizeOutcome.frontmatter } : {}),
     };
+    // 7c. Noise gate (#580): never queue a proposal whose sanitized content is
+    // identical to the current asset (empty diff) or differs only cosmetically
+    // (whitespace reflow, code-fence language hints, YAML scalar re-folding).
+    // Pure deterministic text comparison — see `reflect-noise.ts`. Runs before
+    // the draftMode branch so self-consistency sampling never votes a no-op
+    // candidate into the queue either. Skipped when there is no source asset
+    // (new-asset proposals have nothing to diff against).
+    if (assetContent !== undefined) {
+        const changeKind = classifyReflectChange(assetContent, payload.content);
+        if (changeKind !== "substantive") {
+            const subreason = changeKind === "noop" ? "reflect_skipped_noop" : "reflect_skipped_cosmetic";
+            emitReflectFailed("no_change", subreason, options.ref, { changeKind });
+            return {
+                schemaVersion: 1,
+                ok: false,
+                reason: "no_change",
+                error: changeKind === "noop"
+                    ? `Reflect skipped: proposed content for ${payload.ref} is identical to the current asset (empty diff); no proposal created.`
+                    : `Reflect skipped: proposed content for ${payload.ref} is a cosmetic-only reformat of the current asset (whitespace/fence/YAML-folding changes); no proposal created.`,
+                ...(options.ref ? { ref: options.ref } : {}),
+                exitCode: result.exitCode,
+            };
+        }
+    }
     // 8. Create the proposal. The proposal queue is the ONLY thing reflect
     // writes — promotion to a real asset is gated by `akm proposal accept`.
     //
@@ -1203,6 +1250,9 @@ export async function akmReflect(options = {}) {
         // `parseAgentProposalPayload` already clamps to [0, 1] and drops non-
         // finite values; `createProposal` runs its own sanitizer as a safety net.
         ...(typeof payload.confidence === "number" ? { confidence: payload.confidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal so it
+        // survives to accept/reject/revert time even across runs. See EligibilitySource.
+        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
     };
     const proposalResult = createProposal(stash, createInput, options.ctx);
     if (isProposalSkipped(proposalResult)) {