akm-cli 0.9.0-beta.4 → 0.9.0-beta.40

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

@@ -35,6 +35,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import contradictionJudgeTemplate from "../../../assets/prompts/contradiction-judge.md" with { type: "text" };
 import { assembleAsset } from "../../../core/asset/asset-serialize.js";
 import { parseFrontmatter } from "../../../core/asset/frontmatter.js";
 import { getDefaultLlmConfig } from "../../../core/config/config.js";
@@ -51,6 +52,13 @@ const MAX_FAMILY_SIZE = 8;
  * families. Prevents runaway LLM usage on stashes with many memories.
  */
 const MAX_PAIRS_PER_RUN = 20;
+/**
+ * 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). Absent confidence fields default to
+ * 1.0 for backward compatibility with older judge responses.
+ */
+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.
@@ -58,34 +66,13 @@ const MAX_PAIRS_PER_RUN = 20;
 const BODY_TRUNCATION = 800;
 // ── Prompt builder ────────────────────────────────────────────────────────────
 function buildContradictionJudgePrompt(a, b) {
-    return [
-        "You are evaluating two derived memory entries to determine if they contain",
-        "directly contradictory factual claims about the same subject.",
-        "",
-        "Memory A:",
-        `Ref: ${a.ref}`,
-        `Description: ${a.description || "(none)"}`,
-        "Content:",
-        "```",
-        a.body.slice(0, BODY_TRUNCATION),
-        "```",
-        "",
-        "Memory B:",
-        `Ref: ${b.ref}`,
-        `Description: ${b.description || "(none)"}`,
-        "Content:",
-        "```",
-        b.body.slice(0, BODY_TRUNCATION),
-        "```",
-        "",
-        "Answer ONLY with valid JSON — no prose, no code fences:",
-        '{"contradicts": true|false, "reason": "<one sentence explaining why or why not>"}',
-        "",
-        "A contradiction means the memories make mutually exclusive factual claims about the",
-        "same topic (e.g. Memory A says 'always use VPN' while Memory B says 'VPN is optional').",
-        "If the memories are complementary, about different topics, or one supersedes the other",
-        "without direct conflict, return false.",
-    ].join("\n");
+    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) {
@@ -256,6 +243,14 @@ export async function detectAndWriteContradictions(stashDir, config, chat = chat
                 }
                 if (!parsed?.contradicts)
                     continue;
+                // Confidence gate: absent field defaults to 1.0 (backward compat with
+                // pre-confidence responses). Do NOT default to 0 — that would silently
+                // disable all detection during the rollout period.
+                const confidence = typeof parsed.confidence === "number" ? parsed.confidence : 1.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 contradiction edges: both members get contradictedBy pointing to each other.
                 try {
                     const wroteA = writeContradictedByEdge(a.filePath, b.ref);

package/dist/commands/improve/outcome-loop.js

@@ -0,0 +1,256 @@
+// 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/.
+// ── Constants ─────────────────────────────────────────────────────────────────
+/**
+ * Weight on the "retrieved-but-never-improved" penalty term. Setting this to
+ * 0 degrades to a pure prediction-error score (no quality filter); setting it
+ * to 1 heavily penalises assets whose retrievals never led to accepted changes.
+ */
+export const OUTCOME_PENALTY_WEIGHT = 0.3;
+/**
+ * EMA decay factor for the expected-retrieval rolling mean (α).
+ * New expected = α × new_count + (1−α) × old_expected.
+ * At α = 0.3 the window is ≈ 3 cycles.
+ */
+export const OUTCOME_EMA_ALPHA = 0.3;
+/**
+ * Maximum K improve cycles for the eligibility-trace window. Retrievals older
+ * than K cycles contribute via the EMA decay naturally (they are already baked
+ * into `expected_retrieval_rate`).
+ */
+export const OUTCOME_TRACE_CYCLES = 5;
+/**
+ * Warm-start cap: the maximum `outcome_score` a brand-new row can be seeded with
+ * (from the utility EMA). Prevents a `[0,1]`-range utility value from generating
+ * a score that the first negative delta could catastrophically invert. Clipped to
+ * the maximum plausible first differential update: `max(0, 1 − 0) = 1`, so cap
+ * at a modest 0.3 to avoid spurious rank-flip on first cycle.
+ */
+export const WARM_START_CAP = 0.3;
+/**
+ * Penalty cap: the minimum outcome_score is capped at this value so a single
+ * very-negative run can't send the score to −∞.
+ */
+export const OUTCOME_SCORE_MIN = -1.0;
+/**
+ * Diversity floor: `outcomeSalience` for any asset is at least this fraction
+ * of the maximum observed `outcome_score` in the table, so rare-but-correct
+ * assets cannot be permanently outcompeted. 0 = disabled (pure competition).
+ */
+export const DIVERSITY_FLOOR_FRACTION = 0.1;
+/**
+ * Default review_pressure increment per negative-feedback retrieval cycle.
+ * Each cycle where negative_feedback_count > 0, pressure increases by this
+ * much (and decreases by REVIEW_PRESSURE_DECAY if no new negatives).
+ */
+export const REVIEW_PRESSURE_INCREMENT = 1;
+/**
+ * Decay per non-negative cycle. Keeps review_pressure from accumulating forever
+ * when an asset's quality problems are addressed and feedback turns positive.
+ */
+export const REVIEW_PRESSURE_DECAY = 1;
+/**
+ * Upsert one asset's outcome row.
+ *
+ * On first call for a ref (no prior row): warm-starts from `utilityScore`.
+ * On subsequent calls: applies the differential update formula.
+ *
+ * Returns the resulting `outcome_score` and `review_pressure` so the caller
+ * can pass them to `computeSalience` without a second read.
+ */
+export function updateAssetOutcome(db, inputs) {
+    const now = inputs.now ?? Date.now();
+    const valence = inputs.valence ?? 0;
+    // Fetch existing row (or undefined for first insert).
+    const existing = getAssetOutcome(db, inputs.ref);
+    const isNewRow = existing === undefined;
+    let outcomeScore;
+    let reviewPressure;
+    let expectedRetrievalRate;
+    if (isNewRow) {
+        // ── Warm-start ─────────────────────────────────────────────────────────
+        // Seed from utility EMA, clipped to [0, WARM_START_CAP].
+        // The warm-start is a non-negative seed; the first real differential update
+        // will adjust it up or down from there.
+        const seedScore = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
+        outcomeScore = seedScore;
+        reviewPressure = 0;
+        // Seed expected_retrieval_rate = 0 (no delta history yet).
+        // Seeding with currentRetrievalCount would produce a large spurious negative
+        // prediction error on the first real cycle (delta ≪ cumulative count).
+        expectedRetrievalRate = 0;
+    }
+    else {
+        // ── Differential update ────────────────────────────────────────────────
+        //
+        // retrieval_delta = current − stored (non-negative — we never go backwards)
+        const retrievalDelta = Math.max(0, inputs.currentRetrievalCount - existing.retrieval_count);
+        // accepted_change_rate = accepted_count / max(1, retrieval_count)
+        const acceptedChangeRate = inputs.acceptedChangeCount / Math.max(1, inputs.currentRetrievalCount);
+        // Differential prediction-error term:
+        // outcome = (retrieval_delta − expected_delta)
+        //           − PENALTY × retrieval_delta × (1 − accepted_change_rate)
+        //           + valence
+        //
+        // Prediction error is computed against the PRIOR stored EMA (before folding
+        // in this cycle's observation), so the current delta cannot leak into its own
+        // expectation. Negative values are intentional — they signal below-average cycles.
+        const expectedDelta = existing.expected_retrieval_rate;
+        const predictionError = retrievalDelta - expectedDelta;
+        // Advance the EMA over the OBSERVED delta (not the cumulative count).
+        // expected' = α × delta + (1−α) × prior_expected
+        expectedRetrievalRate =
+            OUTCOME_EMA_ALPHA * retrievalDelta + (1 - OUTCOME_EMA_ALPHA) * existing.expected_retrieval_rate;
+        const penalty = OUTCOME_PENALTY_WEIGHT * retrievalDelta * (1 - acceptedChangeRate);
+        // Running sum (EMA approach): new score = α × update + (1−α) × old
+        // so the score tracks the moving signal, not the cumulative sum.
+        const rawUpdate = predictionError - penalty + valence;
+        const newScore = OUTCOME_EMA_ALPHA * rawUpdate + (1 - OUTCOME_EMA_ALPHA) * existing.outcome_score;
+        // Clip to [OUTCOME_SCORE_MIN, +Infinity) — no upper cap so that very-active
+        // useful assets can accumulate a high positive score.
+        outcomeScore = Math.max(OUTCOME_SCORE_MIN, newScore);
+        // ── review_pressure (#613) ─────────────────────────────────────────────
+        // New negatives this cycle.
+        const newNegatives = Math.max(0, inputs.negativeFeedbackCount - existing.negative_feedback_count);
+        if (newNegatives > 0) {
+            reviewPressure = Math.min(10, existing.review_pressure + REVIEW_PRESSURE_INCREMENT * newNegatives);
+        }
+        else {
+            // Decay when no new negatives.
+            reviewPressure = Math.max(0, existing.review_pressure - REVIEW_PRESSURE_DECAY);
+        }
+    }
+    // Upsert the row.
+    db.prepare(`INSERT INTO asset_outcome
+       (asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+        negative_feedback_count, accepted_change_count, review_pressure,
+        outcome_score, updated_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(asset_ref) DO UPDATE SET
+       last_retrieved_at      = excluded.last_retrieved_at,
+       retrieval_count        = excluded.retrieval_count,
+       expected_retrieval_rate= excluded.expected_retrieval_rate,
+       negative_feedback_count= excluded.negative_feedback_count,
+       accepted_change_count  = excluded.accepted_change_count,
+       review_pressure        = excluded.review_pressure,
+       outcome_score          = excluded.outcome_score,
+       updated_at             = excluded.updated_at`).run(inputs.ref, inputs.lastRetrievedAt, inputs.currentRetrievalCount, expectedRetrievalRate, inputs.negativeFeedbackCount, inputs.acceptedChangeCount, reviewPressure, outcomeScore, now);
+    return { outcomeScore, reviewPressure, isNewRow };
+}
+// ── Reader ────────────────────────────────────────────────────────────────────
+/**
+ * Load the outcome row for one asset, or `undefined` if not yet written.
+ */
+export function getAssetOutcome(db, ref) {
+    const row = db
+        .prepare(`SELECT asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+              negative_feedback_count, accepted_change_count, review_pressure,
+              outcome_score, updated_at
+       FROM asset_outcome WHERE asset_ref = ?`)
+        .get(ref);
+    return row == null ? undefined : row;
+}
+/**
+ * Load ALL asset_outcome rows. Used for the proxy-adequacy tripwire computation.
+ */
+export function getAllAssetOutcomes(db) {
+    return db
+        .prepare(`SELECT asset_ref, last_retrieved_at, retrieval_count, expected_retrieval_rate,
+              negative_feedback_count, accepted_change_count, review_pressure,
+              outcome_score, updated_at
+       FROM asset_outcome ORDER BY asset_ref`)
+        .all();
+}
+/**
+ * Build a Map<ref, outcome_score> for a set of refs in one query.
+ * Used by `salience.ts` to populate `outcomeSalience`.
+ */
+export function getOutcomeScoresByRef(db, refs) {
+    const result = new Map();
+    if (refs.length === 0)
+        return result;
+    const CHUNK = 500;
+    for (let i = 0; i < refs.length; i += CHUNK) {
+        const chunk = refs.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT asset_ref, outcome_score FROM asset_outcome WHERE asset_ref IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            result.set(row.asset_ref, row.outcome_score);
+        }
+    }
+    return result;
+}
+// ── outcomeSalience projection ────────────────────────────────────────────────
+/**
+ * Convert a raw `outcome_score` (differential, may be negative) to a
+ * `outcomeSalience` value in [0, 1] suitable for use in the salience projection.
+ *
+ * Approach:
+ *   1. Clip negative scores to 0 (a negative outcome just means "below expected",
+ *      not "irrelevant"; it should not harm the base retrieval/encoding ranking).
+ *   2. Apply the diversity floor so rare-but-correct assets always retain a
+ *      minimum `outcomeSalience` relative to the stash-wide maximum.
+ *   3. Normalise by `maxScore` (the stash-wide max outcome_score) so the term
+ *      lives in [0, 1]. When maxScore ≤ 0 (all seeds, nothing observed yet),
+ *      return the floor (or 0 if DIVERSITY_FLOOR_FRACTION = 0).
+ *
+ * @param outcomeScore - Raw outcome_score from asset_outcome.
+ * @param maxScore     - Maximum outcome_score across ALL rows (≥ 0 after clip).
+ *                       Callers must compute this once per batch and pass it in.
+ */
+export function outcomeScoreToSalience(outcomeScore, maxScore) {
+    const clipped = Math.max(0, outcomeScore);
+    if (maxScore <= 0) {
+        // No positive scores observed yet — return diversity floor.
+        return DIVERSITY_FLOOR_FRACTION;
+    }
+    const normalised = clipped / maxScore;
+    // Apply diversity floor.
+    return Math.max(DIVERSITY_FLOOR_FRACTION, normalised);
+}
+/**
+ * Compute `corr(outcome_score, accepted_change_rate)` across all asset_outcome
+ * rows. Returns `{correlation: NaN, n, isInverted: false}` when there is
+ * insufficient data (fewer than 3 rows or zero variance in either variable).
+ *
+ * A NEGATIVE correlation means: assets with a HIGH outcome_score have a LOW
+ * accepted_change_rate — i.e. the assets the proxy rates as "doing well"
+ * (frequently retrieved) are precisely the ones that rarely yield an accepted
+ * improvement. That inverts the proxy: high outcome_score ≠ "doing well", so the
+ * coarse retrieval-delta signal is no longer trustworthy and the 0.10+ rich
+ * signal is due. (`isInverted = correlation < -0.3`.)
+ */
+export function computeProxyAdequacy(rows) {
+    const n = rows.length;
+    if (n < 3)
+        return { correlation: Number.NaN, n, isInverted: false };
+    // accepted_change_rate per row.
+    const xs = rows.map((r) => r.outcome_score);
+    const ys = rows.map((r) => r.accepted_change_count / Math.max(1, r.retrieval_count));
+    const meanX = xs.reduce((a, b) => a + b, 0) / n;
+    const meanY = ys.reduce((a, b) => a + b, 0) / n;
+    let covXY = 0;
+    let varX = 0;
+    let varY = 0;
+    for (let i = 0; i < n; i++) {
+        const dx = xs[i] - meanX;
+        const dy = ys[i] - meanY;
+        covXY += dx * dy;
+        varX += dx * dx;
+        varY += dy * dy;
+    }
+    covXY /= n;
+    varX /= n;
+    varY /= n;
+    const denom = Math.sqrt(varX) * Math.sqrt(varY);
+    if (denom < 1e-12)
+        return { correlation: Number.NaN, n, isInverted: false };
+    const correlation = covXY / denom;
+    // Inverted proxy: negative correlation between outcome and accepted_change_rate
+    // means high-outcome assets are also high-need — the opposite of "useful".
+    const isInverted = correlation < -0.3;
+    return { correlation, n, isInverted };
+}

package/dist/commands/improve/proactive-maintenance.js

@@ -0,0 +1,115 @@
+// 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 { computeSalience } from "./salience.js";
+/** One day in milliseconds. */
+const DAY_MS = 86_400_000;
+/** Default staleness gate: an asset is due when last reflected > this many days ago (or never). */
+export const DEFAULT_DUE_DAYS = 30;
+/** Default bound on how many assets the selector surfaces per run. */
+export const DEFAULT_MAX_PER_RUN = 25;
+/** Lower bound on size used in the cost denominator so tiny files don't divide by ~0. */
+const SIZE_FLOOR_BYTES = 200;
+/** Parse the bare asset type out of a `type:name` ref. Returns "" when unparseable. */
+function refType(ref) {
+    const i = ref.indexOf(":");
+    return i > 0 ? ref.slice(0, i) : "";
+}
+/**
+ * Score and select due assets for proactive maintenance.
+ *
+ * Priority: delegates to `computeSalience(...).rankScore` (WS-1 unified salience
+ * vector). The ranking key is therefore identical to every other selector that
+ * uses salience — a single formula governs attention across the whole improve loop.
+ *
+ * DUE gate: an asset is eligible only if it was never reflected OR last
+ * reflected/distilled more than `dueDays` ago. The same gate doubles as the
+ * ROTATION cooldown — a freshly-reflected asset is excluded until it ages back
+ * past `dueDays`, so successive runs rotate through the due pool rather than
+ * re-selecting the same heads. Non-due assets never enter the selection.
+ */
+export function selectProactiveMaintenanceRefs(params) {
+    const now = params.now ?? Date.now();
+    const dueDays = params.dueDays ?? DEFAULT_DUE_DAYS;
+    const maxPerRun = params.maxPerRun ?? DEFAULT_MAX_PER_RUN;
+    const scored = [];
+    for (const candidate of params.candidates) {
+        const ref = candidate.ref;
+        const type = refType(ref);
+        // Staleness from the most recent of reflect/distill — either one touching
+        // the asset resets its maintenance clock.
+        const reflectIso = params.lastReflectTs.get(ref);
+        const distillIso = params.lastDistillTs.get(ref);
+        let lastTouchMs = 0;
+        if (reflectIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(reflectIso) || 0);
+        if (distillIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(distillIso) || 0);
+        const neverReflected = lastTouchMs === 0;
+        const staleDays = neverReflected ? Number.POSITIVE_INFINITY : (now - lastTouchMs) / DAY_MS;
+        // DUE / rotation gate.
+        const due = neverReflected || staleDays > dueDays;
+        // Retrieval frequency (for salience inputs).
+        const retrievalFreq = params.retrievalCounts.get(ref) ?? 0;
+        const lastUse = params.lastUseMs?.get(ref) ?? 0;
+        // Size proxy (cost): kept for salience input — computeSalience applies
+        // the log10 denominator internally.
+        let sizeBytes = params.sizeBytesOf?.(candidate) ?? 0;
+        if (!sizeBytes || sizeBytes < 0)
+            sizeBytes = SIZE_FLOOR_BYTES;
+        // Unified priority via WS-1 salience vector (replaces the old inline formula).
+        const priority = computeSalience({ ref, type, retrievalFreq, lastUseMs: lastUse, sizeBytes, now }).rankScore;
+        scored.push({
+            ref: candidate,
+            type,
+            staleDays,
+            neverReflected,
+            retrievalFreq,
+            sizeBytes,
+            priority,
+            due,
+        });
+    }
+    const dueScored = scored.filter((s) => s.due);
+    const dueTotal = dueScored.length;
+    const neverReflected = dueScored.filter((s) => s.neverReflected).length;
+    // Rank due assets by composite priority (desc). Ties broken by staleness
+    // (older first) then ref string for deterministic ordering.
+    const ranked = dueScored.slice().sort((a, b) => {
+        if (b.priority !== a.priority)
+            return b.priority - a.priority;
+        if (b.staleDays !== a.staleDays)
+            return b.staleDays - a.staleDays;
+        return a.ref.ref < b.ref.ref ? -1 : a.ref.ref > b.ref.ref ? 1 : 0;
+    });
+    const selected = ranked.slice(0, Math.max(0, maxPerRun)).map((s) => s.ref);
+    return { selected, dueTotal, neverReflected, scored };
+}
+/**
+ * Post-lock re-filter for proactive refs.
+ *
+ * Called INSIDE the reflect-distill.lock window with freshly-read timestamp
+ * maps so that any `reflect_invoked` events committed by a concurrent run
+ * while this run was waiting for the lock are visible. Refs that became
+ * non-due (staleDays ≤ dueDays) since planning time are dropped before
+ * execution, closing the SELECT-time cooldown race.
+ *
+ * The logic mirrors the DUE gate in `selectProactiveMaintenanceRefs` — an
+ * asset is due only when never touched OR last touched more than `dueDays`
+ * ago. The selector and this filter must always agree on the gate predicate.
+ */
+export function filterProactiveDue(selected, lastReflectTs, lastDistillTs, dueDays, now) {
+    return selected.filter((candidate) => {
+        const ref = candidate.ref;
+        const reflectIso = lastReflectTs.get(ref);
+        const distillIso = lastDistillTs.get(ref);
+        let lastTouchMs = 0;
+        if (reflectIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(reflectIso) || 0);
+        if (distillIso)
+            lastTouchMs = Math.max(lastTouchMs, Date.parse(distillIso) || 0);
+        const neverReflected = lastTouchMs === 0;
+        const staleDays = neverReflected ? Number.POSITIVE_INFINITY : (now - lastTouchMs) / DAY_MS;
+        return neverReflected || staleDays > dueDays;
+    });
+}