akm-cli 0.9.0-beta.1 → 0.9.0-beta.11

package/dist/commands/health.js

@@ -4,11 +4,13 @@
 import fs from "node:fs";
 import { ConfigError, UsageError } from "../core/errors.js";
 import { appendEvent, readEvents } from "../core/events.js";
+import { buildTaskRunId, getLoggedRunIds, openLogsDatabase } from "../core/logs-db.js";
 import { getStateDbPathInDataDir } from "../core/paths.js";
 import { listExistingTableNames, openStateDatabase, queryCompletedTaskIntervals, queryImproveRuns, queryTaskHistory, } from "../core/state-db.js";
 import { parseSinceToIso } from "../core/time.js";
 import { readSemanticStatus } from "../indexer/search/semantic-status.js";
 import { getExecutionLogCandidates } from "../integrations/session-logs/index.js";
+import { LLM_USAGE_EVENT } from "../llm/usage-persist.js";
 import { HEALTH_CHECKS } from "./health/checks.js";
 const DEFAULT_SINCE_MS = 24 * 60 * 60 * 1000;
 const IMPROVE_COMPLETED_EVENT = "improve_completed";
@@ -471,7 +473,10 @@ function finalizeImproveMetrics(metrics) {
  */
 function mergeImproveMetrics(dst, src) {
     dst.plannedRefs += src.plannedRefs;
-    dst.profileFilteredRefs += src.profileFilteredRefs;
+    // profileFilteredRefs is the count of refs the planner drops up-front for the
+    // active profile — recomputed against the (stable) stash every run, so it is a
+    // snapshot, NOT a per-run increment. Summing it re-counts the same refs each
+    // run (the ~2.4M bug). Set from the most recent run in summarizeImproveRuns.
     dst.actions.reflect.ok += src.actions.reflect.ok;
     dst.actions.reflect.failed += src.actions.reflect.failed;
     dst.actions.reflect.cooldown += src.actions.reflect.cooldown;
@@ -504,8 +509,10 @@ function mergeImproveMetrics(dst, src) {
     dst.coverageGapCount += src.coverageGapCount;
     dst.evalCasesWritten += src.evalCasesWritten;
     dst.deadUrlCount += src.deadUrlCount;
-    dst.memorySummary.eligible += src.memorySummary.eligible;
-    dst.memorySummary.derived += src.memorySummary.derived;
+    // NOTE: memorySummary (derived/eligible) is a WHOLE-STASH snapshot recorded on
+    // every run, NOT a per-run increment — summing it across the window inflates
+    // it ~N× (the 1.2M-eligible bug). It is set from the most recent run in
+    // summarizeImproveRuns instead, so it is intentionally not merged here.
     dst.memoryCleanup.pruneCandidates += src.memoryCleanup.pruneCandidates;
     dst.memoryCleanup.contradictionCandidates += src.memoryCleanup.contradictionCandidates;
     dst.memoryCleanup.beliefStateTransitions += src.memoryCleanup.beliefStateTransitions;
@@ -566,6 +573,11 @@ function summarizeImproveRuns(db, since, until) {
         memoryInference: [],
         graphExtraction: [],
     };
+    // memorySummary is a whole-stash snapshot per run, so the window value is the
+    // MOST RECENT run's snapshot (current state) — not a sum across runs.
+    let latestStartMs = Number.NEGATIVE_INFINITY;
+    let latestMemorySummary;
+    let latestProfileFilteredRefs = 0;
     for (const row of rows) {
         let result;
         try {
@@ -576,6 +588,12 @@ function summarizeImproveRuns(db, since, until) {
         }
         const perRow = projectRunMetrics(result);
         mergeImproveMetrics(accum, perRow);
+        const startMs = new Date(row.started_at).getTime();
+        if (Number.isFinite(startMs) && startMs >= latestStartMs) {
+            latestStartMs = startMs;
+            latestMemorySummary = perRow.memorySummary;
+            latestProfileFilteredRefs = perRow.profileFilteredRefs;
+        }
         // Collect per-phase durations directly off the envelope. consolidation's
         // duration lives inside the sub-object; memoryInference and graphExtraction
         // expose top-level *DurationMs keys (`memoryInferenceDurationMs`,
@@ -592,6 +610,9 @@ function summarizeImproveRuns(db, since, until) {
             phaseDurations.graphExtraction.push(graphMs);
     }
     finalizeImproveMetrics(accum);
+    if (latestMemorySummary)
+        accum.memorySummary = latestMemorySummary;
+    accum.profileFilteredRefs = latestProfileFilteredRefs;
     accum.wallTime.byPhase = {
         consolidation: summarizePhaseDurations(phaseDurations.consolidation),
         memoryInference: summarizePhaseDurations(phaseDurations.memoryInference),
@@ -622,7 +643,7 @@ function summarizePhaseDurations(samples) {
  * Project an improve_runs row + wall-time lookup into a single ImproveRunSummary.
  * Used by `akm health --detail per-run`.
  */
-function projectImproveRunSummary(row, wallTimeMs) {
+function projectImproveRunSummary(row, wallTimeMs, taskId) {
     let result = {};
     try {
         result = JSON.parse(row.result_json);
@@ -646,6 +667,7 @@ function projectImproveRunSummary(row, wallTimeMs) {
             mode: row.scope_mode,
             ...(row.scope_value ? { value: row.scope_value } : {}),
         },
+        taskId,
         actions: perRow.actions,
         memorySummary: perRow.memorySummary,
         memoryCleanup: perRow.memoryCleanup,
@@ -708,9 +730,62 @@ function findContainingTaskInterval(timestampMs, intervals) {
     }
     return undefined;
 }
+/**
+ * Load `task_history` rows whose `task_id` begins `akm-improve` (the scheduled
+ * improve tasks: `akm-improve-frequent`, `akm-improve-proactive-weekly`, …) in
+ * the window, widened ±5 min so a task that fired just before the window opened
+ * still matches a run inside it. Used to attribute each improve run to the task
+ * that launched it.
+ */
+function loadImproveTaskRuns(db, since, until) {
+    const sinceMs = new Date(since).getTime();
+    const untilMs = until ? new Date(until).getTime() : undefined;
+    const widenedSince = new Date(sinceMs - 5 * 60 * 1000).toISOString();
+    const widenedUntil = untilMs !== undefined ? new Date(untilMs + 5 * 60 * 1000).toISOString() : undefined;
+    const runs = [];
+    for (const row of queryTaskHistory(db, { since: widenedSince, until: widenedUntil })) {
+        if (!row.task_id.startsWith("akm-improve"))
+            continue;
+        const startMs = new Date(row.started_at).getTime();
+        if (!Number.isFinite(startMs))
+            continue;
+        const endIso = row.completed_at ?? row.failed_at;
+        const endMs = endIso ? new Date(endIso).getTime() : Number.NaN;
+        runs.push({ taskId: row.task_id, startMs, endMs });
+    }
+    return runs;
+}
+/**
+ * Attribute an improve run to the scheduled task that launched it by matching
+ * start times within ±5 min, scored by start delta (plus end delta when both
+ * ends are known). Port of the health-report skill's `match_task_id`. Returns
+ * `"manual"` when no scheduled improve task matches.
+ */
+function matchImproveTaskId(startedAt, completedAt, taskRuns) {
+    const startMs = new Date(startedAt).getTime();
+    if (!Number.isFinite(startMs))
+        return "manual";
+    const endMs = completedAt ? new Date(completedAt).getTime() : Number.NaN;
+    let best;
+    let bestScore = Number.POSITIVE_INFINITY;
+    for (const task of taskRuns) {
+        const startDelta = Math.abs(task.startMs - startMs);
+        if (startDelta > 5 * 60 * 1000)
+            continue;
+        let score = startDelta;
+        if (Number.isFinite(endMs) && Number.isFinite(task.endMs))
+            score += Math.abs(task.endMs - endMs);
+        if (score < bestScore) {
+            bestScore = score;
+            best = task.taskId;
+        }
+    }
+    return best ?? "manual";
+}
 function buildPerRunSummaries(db, since, until) {
     const rows = queryImproveRuns(db, since, until);
     const taskIntervals = loadTaskIntervals(db, since, until);
+    const improveTaskRuns = loadImproveTaskRuns(db, since, until);
     const summaries = [];
     for (const row of rows) {
         const startMs = new Date(row.started_at).getTime();
@@ -730,7 +805,8 @@ function buildPerRunSummaries(db, since, until) {
             const interval = Number.isFinite(startMs) ? findContainingTaskInterval(startMs, taskIntervals) : undefined;
             wallTimeMs = interval?.durationMs ?? 0;
         }
-        summaries.push(projectImproveRunSummary(row, wallTimeMs));
+        const taskId = matchImproveTaskId(row.started_at, row.completed_at, improveTaskRuns);
+        summaries.push(projectImproveRunSummary(row, wallTimeMs, taskId));
     }
     return summaries;
 }
@@ -757,12 +833,34 @@ function computeWallTimeStats(durationsMs, byPhase) {
     };
 }
 function buildImproveSkipSummary(events) {
-    const skipReasons = {};
+    // Two kinds of skip events:
+    //  - Per-occurrence (no `count`): one event per skipped ref → SUM is correct.
+    //  - Aggregated snapshot (carries `count`): a single per-run event whose count
+    //    is the number of refs that hit a STABLE, whole-stash condition that run
+    //    (`no_new_signal`, `profile_filtered_all_passes`). Each run re-counts the
+    //    same stable set, so summing across the window re-counts it N times (the
+    //    2.7M / 3M inflation). For these we keep the MOST RECENT run's count — the
+    //    current snapshot — matching how memorySummary/profileFilteredRefs are
+    //    handled. Events arrive in chronological (offset) order, so the last
+    //    count-bearing event per reason is the latest run's value.
+    const summed = {};
+    const latestSnapshot = {};
     for (const event of events) {
         const reason = typeof event.metadata?.reason === "string" && event.metadata.reason.trim() ? event.metadata.reason : "unknown";
-        skipReasons[reason] = (skipReasons[reason] ?? 0) + 1;
+        const rawCount = event.metadata?.count;
+        if (typeof rawCount === "number" && Number.isFinite(rawCount) && rawCount > 0) {
+            latestSnapshot[reason] = rawCount; // overwrite → keeps the latest run's snapshot
+        }
+        else {
+            summed[reason] = (summed[reason] ?? 0) + 1;
+        }
     }
-    return { skipped: events.length, skipReasons };
+    const skipReasons = { ...summed };
+    for (const [reason, count] of Object.entries(latestSnapshot)) {
+        skipReasons[reason] = (skipReasons[reason] ?? 0) + count;
+    }
+    const skipped = Object.values(skipReasons).reduce((a, b) => a + b, 0);
+    return { skipped, skipReasons };
 }
 function probeStateDbRoundTrip(stateDbPath) {
     const before = readEvents({}, { dbPath: stateDbPath }).nextOffset;
@@ -882,14 +980,84 @@ function computeDeltas(first, last) {
     }
     return out;
 }
-function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now()) {
+/**
+ * Partition task_history rows into "should have a log" (non-null log_path) and
+ * "log is actually backed". A run counts as backed when logs.db holds rows for
+ * its run_id (#579 — the DB is the primary record); rows written before logs.db
+ * existed fall back to the transitional on-disk file check. `logsDb` may be
+ * undefined when logs.db could not be opened — then only the file check runs.
+ */
+function partitionLogBackedRows(taskRows, logsDb) {
+    const withLogs = taskRows.filter((row) => row.log_path !== null);
+    const loggedRunIds = logsDb
+        ? getLoggedRunIds(logsDb, withLogs.map((row) => buildTaskRunId(row.task_id, row.started_at)))
+        : new Set();
+    const backed = withLogs.filter((row) => loggedRunIds.has(buildTaskRunId(row.task_id, row.started_at)) ||
+        (row.log_path !== null && fs.existsSync(row.log_path)));
+    return { withLogs, backed };
+}
+/** Stage key used for `llm_usage` events recorded outside any stage scope. */
+const UNATTRIBUTED_STAGE = "unattributed";
+function emptyLlmUsageStageAggregate() {
+    return {
+        calls: 0,
+        totalDurationMs: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+function emptyLlmUsageAggregate() {
+    return { ...emptyLlmUsageStageAggregate(), byStage: {} };
+}
+/**
+ * Aggregate `llm_usage` events (#576) into a window total plus a per-stage
+ * breakdown of call count, wall-time, and token usage. Token fields absent from
+ * a best-effort record contribute 0. Calls with no `stage` land under
+ * {@link UNATTRIBUTED_STAGE}.
+ */
+function summarizeLlmUsage(events) {
+    const aggregate = emptyLlmUsageAggregate();
+    for (const event of events) {
+        const meta = event.metadata ?? {};
+        const stageKey = typeof meta.stage === "string" && meta.stage ? meta.stage : UNATTRIBUTED_STAGE;
+        let stage = aggregate.byStage[stageKey];
+        if (!stage) {
+            stage = emptyLlmUsageStageAggregate();
+            aggregate.byStage[stageKey] = stage;
+        }
+        const durationMs = toFiniteNumber(meta.durationMs);
+        const promptTokens = toFiniteNumber(meta.promptTokens);
+        const completionTokens = toFiniteNumber(meta.completionTokens);
+        const totalTokens = toFiniteNumber(meta.totalTokens);
+        const reasoningTokens = toFiniteNumber(meta.reasoningTokens);
+        for (const target of [aggregate, stage]) {
+            target.calls += 1;
+            target.totalDurationMs += durationMs;
+            target.promptTokens += promptTokens;
+            target.completionTokens += completionTokens;
+            target.totalTokens += totalTokens;
+            target.reasoningTokens += reasoningTokens;
+        }
+    }
+    return aggregate;
+}
+function readLlmUsageAggregate(stateDbPath, since, until) {
+    const events = readEvents({ since, type: LLM_USAGE_EVENT }, { dbPath: stateDbPath }).events.filter((event) => {
+        if (until === undefined)
+            return true;
+        return new Date(event.ts ?? since).getTime() < new Date(until).getTime();
+    });
+    return summarizeLlmUsage(events);
+}
+function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now(), logsDb) {
     const taskRows = queryTaskHistory(db, { since }).filter((row) => {
         const startMs = new Date(row.started_at).getTime();
         const untilMs = new Date(until).getTime();
         return !Number.isFinite(untilMs) || startMs < untilMs;
     });
-    const taskRowsWithLogs = taskRows.filter((row) => row.log_path !== null);
-    const existingLogRows = taskRowsWithLogs.filter((row) => row.log_path && fs.existsSync(row.log_path));
+    const { withLogs: taskRowsWithLogs, backed: existingLogRows } = partitionLogBackedRows(taskRows, logsDb);
     const failedTaskRows = taskRows.filter((row) => row.status === "failed");
     const activeRows = taskRows.filter((row) => row.status === "active");
     const stuckActiveRuns = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
@@ -923,6 +1091,7 @@ function buildWindowMetrics(db, stateDbPath, since, until, now = () => Date.now(
         stuckActiveRuns,
         logBackingRate: roundRate(logBackingRate),
         probeRoundTripMs: null,
+        llmUsage: readLlmUsageAggregate(stateDbPath, since, until),
     };
     return { improve: improveSummary, metrics, runs: runCount };
 }
@@ -961,6 +1130,16 @@ export function akmHealth(options = {}) {
     catch (error) {
         throw new ConfigError(`Unable to open state.db: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
     }
+    // logs.db backs the log-backing metric (#579). Best-effort: when it cannot
+    // be opened, partitionLogBackedRows falls back to the on-disk file check, so
+    // health never hard-fails on a missing/locked logs database.
+    let logsDb;
+    try {
+        logsDb = openLogsDatabase(options.logsDbPath);
+    }
+    catch {
+        logsDb = undefined;
+    }
     try {
         const tables = listExistingTableNames(db, ["events", "task_history", "proposals", "schema_migrations"]);
         const tableNames = tables.map((row) => row.name).sort();
@@ -968,8 +1147,7 @@ export function akmHealth(options = {}) {
         const missingTables = requiredTables.filter((name) => !tableNames.includes(name));
         const probe = probeStateDbRoundTrip(stateDbPath);
         const taskRows = queryTaskHistory(db, { since });
-        const taskRowsWithLogs = taskRows.filter((row) => row.log_path !== null);
-        const existingLogRows = taskRowsWithLogs.filter((row) => row.log_path && fs.existsSync(row.log_path));
+        const { withLogs: taskRowsWithLogs, backed: existingLogRows } = partitionLogBackedRows(taskRows, logsDb);
         const failedTaskRows = taskRows.filter((row) => row.status === "failed");
         const activeRows = taskRows.filter((row) => row.status === "active");
         const stuckActiveRuns = activeRows.filter((row) => now() - new Date(row.started_at).getTime() > ACTIVE_RUN_WARN_MS).length;
@@ -1041,6 +1219,7 @@ export function akmHealth(options = {}) {
             stuckActiveRuns,
             logBackingRate: roundRate(logBackingRate),
             probeRoundTripMs: probe.durationMs,
+            llmUsage: readLlmUsageAggregate(stateDbPath, since),
         };
         const hardFailure = hardChecks.some((check) => check.status === "fail");
         const deterministicWarnings = [...hardChecks, ...advisories].some((check) => check.status === "warn" && check.kind === "deterministic");
@@ -1062,7 +1241,7 @@ export function akmHealth(options = {}) {
             windowResults = windowSpecs.map((spec) => {
                 const winSince = parseHealthSince(spec.since);
                 const winUntil = spec.until ? parseHealthSince(spec.until) : new Date(now()).toISOString();
-                const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now);
+                const bundle = buildWindowMetrics(db, stateDbPath, winSince, winUntil, now, logsDb);
                 return {
                     name: spec.name,
                     since: winSince,
@@ -1112,6 +1291,14 @@ export function akmHealth(options = {}) {
     }
     finally {
         db.close();
+        if (logsDb) {
+            try {
+                logsDb.close();
+            }
+            catch {
+                // best-effort
+            }
+        }
     }
 }
 // ── Markdown renderers ───────────────────────────────────────────────────────

package/dist/commands/improve/consolidate.js

@@ -809,7 +809,7 @@ export async function akmConsolidate(opts = {}) {
         };
     }
     if (opts.incrementalSince) {
-        memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings);
+        memories = narrowToIncrementalCandidates(memories, opts.incrementalSince, warnings, opts.neighborsPerChanged);
         if (memories.length === 0) {
             return {
                 schemaVersion: 1,
@@ -828,6 +828,27 @@ export async function akmConsolidate(opts = {}) {
             };
         }
     }
+    if (opts.limit !== undefined && memories.length > opts.limit) {
+        // Order oldest-modified-first before capping so the limit selects the
+        // stalest memories rather than a fixed head of the (rowid-ordered) DB
+        // query. Consolidation rewrites surviving files, bumping their mtime, so
+        // processed memories drift to the back of the queue and the cap rotates
+        // across the whole corpus over successive runs instead of revisiting the
+        // same slice every time. Fail-open to 0 (front of queue) when a file can
+        // no longer be stat'd.
+        const mtimeOf = (m) => {
+            try {
+                return fs.statSync(m.filePath).mtimeMs;
+            }
+            catch {
+                return 0;
+            }
+        };
+        const mtimeCache = new Map(memories.map((m) => [m.filePath, mtimeOf(m)]));
+        memories = [...memories].sort((a, b) => (mtimeCache.get(a.filePath) ?? 0) - (mtimeCache.get(b.filePath) ?? 0));
+        warnings.push(`Consolidation: pool capped at ${opts.limit} of ${memories.length} memories (limit option, oldest-modified first).`);
+        memories = memories.slice(0, opts.limit);
+    }
     // Consolidation always uses the HTTP LLM client directly — never the agent
     // CLI. The agent CLI is for interactive agent sessions (reflect, propose);
     // structured JSON generation works better and faster via HTTP.
@@ -1992,10 +2013,23 @@ async function checkPreEmitDedup(opts) {
  * everything changed or the index can't answer (fail-open to preserve merge
  * correctness). `since` is an ISO timestamp.
  */
-export function narrowToIncrementalCandidates(memories, since, warnings) {
+/**
+ * Parse a human-readable duration string (e.g. "30m", "24h", "7d") to an ISO
+ * timestamp representing `now - duration`. Returns the input unchanged when it
+ * doesn't match the pattern (assumed to already be an ISO timestamp).
+ */
+function parseSinceToIso(since) {
+    const m = since.match(/^(\d+)(m|h|d)$/);
+    if (!m)
+        return since;
+    const multiplier = { m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+    return new Date(Date.now() - parseInt(m[1], 10) * multiplier).toISOString();
+}
+export function narrowToIncrementalCandidates(memories, since, warnings, neighborsPerChanged = 5) {
+    const sinceIso = parseSinceToIso(since);
     const isChanged = (m) => {
         try {
-            return fs.statSync(m.filePath).mtime.toISOString() > since;
+            return fs.statSync(m.filePath).mtime.toISOString() > sinceIso;
         }
         catch {
             return true; // never silently drop a memory we cannot stat
@@ -2006,7 +2040,6 @@ export function narrowToIncrementalCandidates(memories, since, warnings) {
         return [];
     if (changed.length === memories.length)
         return memories;
-    const NEIGHBORS_PER_CHANGED = 5;
     const byName = new Map(memories.map((m) => [m.name, m]));
     const keep = new Set(changed.map((m) => m.name));
     let db;
@@ -2016,7 +2049,7 @@ export function narrowToIncrementalCandidates(memories, since, warnings) {
             const id = findEntryIdByRef(db, `memory:${m.name}`);
             if (id === undefined)
                 continue;
-            for (const hit of getNeighborsByEntryId(db, id, NEIGHBORS_PER_CHANGED + 1)) {
+            for (const hit of getNeighborsByEntryId(db, id, neighborsPerChanged + 1)) {
                 if (hit.id === id)
                     continue;
                 const entry = getEntryById(db, hit.id);
@@ -2037,7 +2070,7 @@ export function narrowToIncrementalCandidates(memories, since, warnings) {
             closeDatabase(db);
     }
     const candidates = memories.filter((m) => keep.has(m.name));
-    warnings.push(`Incremental consolidation: ${changed.length} changed + neighbours → ${candidates.length}/${memories.length} memories considered (since ${since}).`);
+    warnings.push(`Incremental consolidation: ${changed.length} changed + neighbours → ${candidates.length}/${memories.length} memories considered (since ${since}${sinceIso !== since ? ` = ${sinceIso}` : ""}).`);
     return candidates;
 }
 function loadMemoriesForSource(source, stashDir, warnings) {

package/dist/commands/improve/distill.js

@@ -586,7 +586,7 @@ similarLessons) {
  * @param reason    - Human-readable rejection reason.
  * @param extraMeta - Optional additional metadata for the event.
  */
-function writeQualityRejection(stash, inputRef, lessonRef, content, score, reason, extraMeta = {}) {
+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");
@@ -602,6 +602,9 @@ function writeQualityRejection(stash, inputRef, lessonRef, content, score, reaso
             score,
             reason,
             ...extraMeta,
+            // Attribution tagging: stamp the eligibility lane so distill_invoked can be
+            // sliced by lane downstream. See EligibilitySource.
+            ...(eligibilitySource ? { eligibilitySource } : {}),
         },
     });
     return {
@@ -629,6 +632,12 @@ export async function akmDistill(options) {
     // Validate the ref shape up front so a typo never reaches the LLM.
     const parsedInputRef = parseAssetRef(inputRef);
     const targetKind = options.proposalKind ?? "lesson";
+    // Attribution tagging: spread into every distill_invoked event's metadata so
+    // the lane that selected this asset is recorded uniformly across all outcome
+    // branches. Empty object when no lane was supplied (direct `akm distill`).
+    const eligMeta = options.eligibilitySource
+        ? { eligibilitySource: options.eligibilitySource }
+        : {};
     // Recursive-distillation guard. Distill produces *lessons* from non-lesson
     // sources (memory, skill, knowledge, etc.). Calling distill on an existing
     // lesson would derive `lesson:lesson-<name>-lesson-lesson` (double `-lesson`
@@ -650,6 +659,7 @@ export async function akmDistill(options) {
                 lessonRef: skippedRef,
                 message: "distill refuses lesson inputs — lessons are the distilled form, not a source",
                 skipReason: "recursive_lesson_input",
+                ...eligMeta,
             },
         });
         return {
@@ -766,6 +776,7 @@ export async function akmDistill(options) {
                             outcome: "skipped",
                             lessonRef: promotion.knowledgeRef,
                             message: "D-1: LLM resolved destination conflict as NOOP — existing content kept",
+                            ...eligMeta,
                         },
                     });
                     return {
@@ -814,9 +825,9 @@ export async function akmDistill(options) {
             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 });
+                    return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, { reviewNeeded: true }, options.eligibilitySource);
                 }
-                return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason);
+                return writeQualityRejection(stash, inputRef, promotion.knowledgeRef, resolvedPromotionContent, judgeResult.score, judgeResult.reason, {}, options.eligibilitySource);
             }
             // Normalize 1-5 judge score to [0, 1]. Score of -1 means pass-through
             // (no LLM / timeout / parse failure) — leave confidence undefined so
@@ -834,6 +845,8 @@ export async function akmDistill(options) {
                 ...(Object.keys(knowledgeParsed.data).length > 0 ? { frontmatter: knowledgeParsed.data } : {}),
             },
             ...(knowledgeJudgeConfidence !== undefined ? { confidence: knowledgeJudgeConfidence } : {}),
+            // Attribution tagging: persist the eligibility lane on the proposal.
+            ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
         }, options.ctx);
         if (isProposalSkipped(proposalResult)) {
             appendEvent({
@@ -844,6 +857,7 @@ export async function akmDistill(options) {
                     lessonRef: promotion.knowledgeRef,
                     message: proposalResult.message,
                     skipReason: proposalResult.reason,
+                    ...eligMeta,
                 },
             });
             return {
@@ -867,6 +881,7 @@ export async function akmDistill(options) {
                 proposalId: proposal.id,
                 ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
                 ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+                ...eligMeta,
             },
         });
         return {
@@ -979,6 +994,7 @@ export async function akmDistill(options) {
                 lessonRef: effectiveLessonRef,
                 proposalKind: effectiveProposalKind,
                 ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+                ...eligMeta,
             },
         });
         return {
@@ -1203,6 +1219,7 @@ export async function akmDistill(options) {
                 proposalKind: effectiveProposalKind,
                 findingKinds: findings.map((f) => f.kind),
                 ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+                ...eligMeta,
             },
         });
         const message = findings.map((f) => f.message).join("\n");
@@ -1224,9 +1241,9 @@ export async function akmDistill(options) {
                 return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, judgeResult.score, judgeResult.reason, {
                     reviewNeeded: true,
                     ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
-                });
+                }, options.eligibilitySource);
             }
-            return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, judgeResult.score, judgeResult.reason, exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {});
+            return writeQualityRejection(stash, inputRef, effectiveLessonRef, content, judgeResult.score, judgeResult.reason, exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}, options.eligibilitySource);
         }
         // Normalize 1-5 judge score to [0, 1]. Score of -1 means pass-through
         // (no LLM / timeout / parse failure) — leave confidence undefined so
@@ -1256,6 +1273,8 @@ export async function akmDistill(options) {
             frontmatter: frontmatterWithSources,
         },
         ...(lessonJudgeConfidence !== undefined ? { confidence: lessonJudgeConfidence } : {}),
+        // Attribution tagging: persist the eligibility lane on the proposal.
+        ...(options.eligibilitySource ? { eligibilitySource: options.eligibilitySource } : {}),
     }, options.ctx);
     if (isProposalSkipped(proposalResult2)) {
         appendEvent({
@@ -1266,6 +1285,7 @@ export async function akmDistill(options) {
                 lessonRef: effectiveLessonRef,
                 message: proposalResult2.message,
                 skipReason: proposalResult2.reason,
+                ...eligMeta,
             },
         });
         return {
@@ -1290,6 +1310,7 @@ export async function akmDistill(options) {
             ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
             ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
             ...(descriptionSwapped > 0 ? { descriptionSwapped } : {}),
+            ...eligMeta,
         },
     });
     return {

package/dist/commands/improve/extract-prompt.js

@@ -55,7 +55,7 @@ export const EXTRACT_JSON_SCHEMA = {
                         type: "string",
                         minLength: 20,
                         maxLength: 400,
-                        description: "One-sentence summary of the candidate. Must be a complete sentence; do not end mid-clause.",
+                        description: "One-sentence summary of the candidate. Must be a complete sentence in active voice. Do NOT start with 'When', 'If', 'How', 'Use', or 'Avoid'. Do NOT end with ':', ';', or ','. Do NOT use heading-fragment text ('Summary', 'Overview', 'Key finding:'). Minimum 20 characters, maximum 400 characters.",
                     },
                     when_to_use: {
                         type: "string",