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

package/dist/commands/improve/related-sessions.js

@@ -0,0 +1,120 @@
+// 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/.
+/**
+ * #627 — getRelatedSessions helper.
+ *
+ * Finds session assets related to a seed by SHARED TAGS / GRAPH ENTITIES —
+ * NEVER embedding similarity. Modeled on recombine.ts buildRelatednessClusters:
+ * two sessions relate when they share at least one *topic* tag or graph entity;
+ * two textually near-identical sessions with no shared topic signal do NOT
+ * relate. This makes the helper a pure query-layer relatedness lookup that
+ * makes NO network / embedding calls.
+ *
+ * The generic base tags every session asset carries (`session` + the harness
+ * id, see session-asset.ts) are IGNORED for relatedness — otherwise every
+ * session would trivially relate to every other. Callers should therefore seed
+ * with derived topic tags, but the helper defensively strips the generic base
+ * tags from candidate sessions too.
+ *
+ * Relatedness source:
+ *   - `"tags"`  — score by count of (seedTags ∩ session tags).
+ *   - `"graph"` — score by count of (seedEntities ∩ session graph entities);
+ *                 falls open to tag relatedness when the graph table is empty.
+ *   - `"both"`  — sum of the tag + entity overlap.
+ */
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { closeDatabase, getAllEntries, getEntitiesByEntryIds, openExistingDatabase, } from "../../indexer/db/db.js";
+/** Generic base tags every session asset carries — never a relatedness signal. */
+const GENERIC_SESSION_TAGS = new Set(["session"]);
+/**
+ * Build the set of topic tags for a session entry, excluding generic base tags
+ * (`session`) and the harness segment of the entry name (the harness id is the
+ * first path component of `<harness>/<id>` and is also carried as a base tag).
+ */
+function topicTagsForSession(entry) {
+    const harness = entry.entry.name.split("/")[0];
+    const result = new Set();
+    for (const tag of entry.entry.tags ?? []) {
+        if (GENERIC_SESSION_TAGS.has(tag))
+            continue;
+        if (harness && tag === harness)
+            continue;
+        result.add(tag);
+    }
+    return result;
+}
+/**
+ * Find session assets related to a seed by shared tags / graph entities.
+ * Relatedness is signal-based, NOT embedding similarity.
+ */
+export function getRelatedSessions(opts) {
+    const seedTags = (opts.seedTags ?? [])
+        .filter((t) => !GENERIC_SESSION_TAGS.has(t))
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const seedEntities = (opts.seedEntities ?? []).map((e) => e.trim().toLowerCase()).filter(Boolean);
+    const minShared = opts.minShared ?? 1;
+    const limit = opts.limit ?? 5;
+    const relatednessSource = opts.relatednessSource ?? "tags";
+    const excludeRefs = new Set(opts.excludeRefs ?? []);
+    // Empty seed input → nothing to relate to.
+    if (seedTags.length === 0 && seedEntities.length === 0)
+        return [];
+    const seedTagSet = new Set(seedTags);
+    const seedEntitySet = new Set(seedEntities);
+    let db = opts.db;
+    let ownsDb = false;
+    if (!db) {
+        db = openExistingDatabase();
+        ownsDb = true;
+    }
+    try {
+        const sessions = getAllEntries(db, "session");
+        // Resolve graph entities for the candidate sessions when requested. Fail
+        // open to tag relatedness when the graph table is empty (no rows).
+        let entityByEntryId;
+        const wantGraph = relatednessSource === "graph" || relatednessSource === "both";
+        if (wantGraph) {
+            try {
+                entityByEntryId = getEntitiesByEntryIds(db, sessions.map((s) => s.id));
+            }
+            catch {
+                entityByEntryId = undefined;
+            }
+        }
+        const hasEntities = !!entityByEntryId && entityByEntryId.size > 0;
+        // Effective signal selection. "graph" with no entities falls open to tags.
+        const useTags = relatednessSource === "tags" || relatednessSource === "both" || (wantGraph && !hasEntities);
+        const useGraph = wantGraph && hasEntities;
+        const scored = [];
+        for (const session of sessions) {
+            const ref = makeAssetRef(session.entry.type, session.entry.name);
+            if (excludeRefs.has(ref))
+                continue;
+            let sharedCount = 0;
+            if (useTags && seedTagSet.size > 0) {
+                for (const tag of topicTagsForSession(session)) {
+                    if (seedTagSet.has(tag))
+                        sharedCount += 1;
+                }
+            }
+            if (useGraph && seedEntitySet.size > 0 && entityByEntryId) {
+                for (const ent of entityByEntryId.get(session.id) ?? []) {
+                    if (seedEntitySet.has(ent))
+                        sharedCount += 1;
+                }
+            }
+            if (sharedCount >= minShared) {
+                scored.push({ ref, name: session.entry.name, sharedCount });
+            }
+        }
+        // Rank by shared-signal count desc, then ref for a deterministic tiebreak.
+        scored.sort((a, b) => b.sharedCount - a.sharedCount || a.ref.localeCompare(b.ref));
+        return scored.slice(0, Math.max(0, limit));
+    }
+    finally {
+        if (ownsDb && db)
+            closeDatabase(db);
+    }
+}

package/dist/commands/improve/salience.js

@@ -0,0 +1,386 @@
+// 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-1 — Unified SALIENCE model (S1 seam).
+ *
+ * Replaces the three competing attention formulas that existed across:
+ *   - proactive-maintenance.ts:186 — `importance × log(1+freq) × recencyDecay / log10(size)`
+ *   - feedback-valence.ts:111      — `combinedEligibilityScore = utility·0.7 + valence·0.3`
+ *   - getUtilityScoresByIds        — MemRL utility EMA (#386)
+ *
+ * ## Salience vector (three independently-stored, independently-decayable sub-scores)
+ *
+ * | Sub-score         | Brain analogy          | Source                          |
+ * |-------------------|------------------------|---------------------------------|
+ * | `encodingSalience`| Amygdala tagging (Gap 1)| Set at extract; v1 = type weight|
+ * | `outcomeSalience` | Dopaminergic outcome   | WS-2 (0 until that lands)       |
+ * | `retrievalSalience`| Hippocampal frequency+recency | usage_events + utility_scores |
+ *
+ * ## Projection
+ *
+ * `rankScore = (w_e·encoding + w_o·outcome + w_r·retrieval) × sizePenalty`, normalized [0,1].
+ *
+ * **WS-2 default-off (Part-V gate):**
+ * `w_o = 0.15` is the target but is applied only when `outcomeWeightEnabled=true`
+ * (set via `improve.salience.outcomeWeightEnabled: true` in config after running
+ * Part-V T0 baseline). Default: WS-1 parity weights `w_e=0.30, w_r=0.70, w_o=0`.
+ * `outcomeSalience` is populated from `asset_outcome.outcome_score` (WS-2) for
+ * observability regardless of the flag.
+ *
+ * ## Plasticity
+ *
+ * `consecutive_no_ops` (INTEGER column in `asset_salience`) dampens CONSOLIDATION-
+ * SELECTION only — it is intentionally NOT applied to `rankScore`, so a stable
+ * asset stays fully retrievable while no longer consuming repeated LLM merge
+ * attempts. See `getConsecutiveNoOps` / `recordNoOp` / `resetConsecutiveNoOps`.
+ *
+ * ## Canonical store
+ *
+ * The three sub-scores live in `state.db :: asset_salience` (canonical).
+ * An optional frontmatter mirror of the stable `encodingSalience` is allowed for
+ * portability (issue #608 may write it there), but state.db is the source of truth
+ * for ranking. This prevents the frontmatter-vs-state.db split that issue #608
+ * would otherwise create (#608 pull-forward decision from Part VI).
+ *
+ * @module salience
+ */
+import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { getAllEntries, getUtilityScoresByIds } from "../../indexer/db/db.js";
+import { WARM_START_CAP } from "./outcome-loop.js";
+// ── One day in ms ─────────────────────────────────────────────────────────────
+const DAY_MS = 86_400_000;
+// ── Recency decay half-life (mirrors the proactive-maintenance prototype) ─────
+const RECENCY_HALFLIFE_DAYS = 21;
+// ── Size proxy floor (avoids log10(0)) ────────────────────────────────────────
+const SIZE_FLOOR_BYTES = 200;
+// ── Projection weights ────────────────────────────────────────────────────────
+//
+// These constants reflect the WS-2 TARGET values (used when outcomeWeightEnabled=true).
+// Default ranking uses WS-1 parity weights (w_e=0.30, w_r=0.70, w_o=0) until the
+// maintainer opts in via `improve.salience.outcomeWeightEnabled: true` after running
+// the Part-V T0 baseline (scripts/akm-eval + health report).
+//
+// WS-2 opt-in split (w_e=0.25, w_o=0.15, w_r=0.60, sum = 1.0):
+// [exp] Expert recommendation: encoding should be moderate so a type-importance
+// stub does not completely dominate; retrieval should be strong since it directly
+// measures use; outcome provides a quality signal proportional to usefulness.
+//
+// Re-tune via the Part-V measurement protocol if the throughput/quality gate
+// shows regression after enabling the outcome weight.
+export const W_ENCODING = 0.25; // WS-2 target encoding weight (w_e)
+export const W_OUTCOME = 0.15; // WS-2 target outcome weight (w_o)
+export const W_RETRIEVAL = 0.6; // WS-2 target retrieval weight (w_r)
+// Compile-time guard: weights must sum to 1.0 (±ε). The TS initializer runs
+// at module load, not build time, so this acts as a startup assertion.
+if (Math.abs(W_ENCODING + W_OUTCOME + W_RETRIEVAL - 1.0) > 1e-9) {
+    throw new Error(`salience.ts: W_ENCODING + W_OUTCOME + W_RETRIEVAL must equal 1.0 (got ${W_ENCODING + W_OUTCOME + W_RETRIEVAL})`);
+}
+// ── WS-1 parity weights ───────────────────────────────────────────────────────
+//
+// These constants reflect the default WS-1 parity weights used when
+// `outcomeWeightEnabled` is false/absent (the default). They preserve the
+// WS-1 two-way split (w_e=0.30, w_r=0.70) with w_o=0 so outcome does not
+// affect rankScore until the operator opts in after the Part-V baseline run.
+//
+// Named here (rather than inline literals in the else branch) so a future
+// re-tune has a single source of truth and the sum-to-1 guard below catches
+// any accidental mis-edit.
+export const W_ENCODING_PARITY = 0.3; // WS-1 parity encoding weight
+export const W_OUTCOME_PARITY = 0; // WS-1 parity outcome weight (0 = disabled)
+export const W_RETRIEVAL_PARITY = 0.7; // WS-1 parity retrieval weight
+// Startup guard: parity triple must also sum to 1.0 (±ε).
+if (Math.abs(W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY - 1.0) > 1e-9) {
+    throw new Error(`salience.ts: W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY must equal 1.0 (got ${W_ENCODING_PARITY + W_OUTCOME_PARITY + W_RETRIEVAL_PARITY})`);
+}
+// ── Type-importance fallback weights (#608 landed) ────────────────────────────
+//
+// The real encoding salience estimator is `scoreEncodingSalience` in
+// `encoding-salience.ts` (#608). These weights are the fallback used when
+// `SalienceInputs.encodingSalience` is absent (pre-#608 assets without a
+// frontmatter `salience:` field or a state.db row seeded by distill).
+export const DEFAULT_TYPE_ENCODING_WEIGHTS = Object.freeze({
+    skill: 0.9,
+    agent: 0.9,
+    command: 0.8,
+    workflow: 0.8,
+    lesson: 0.75,
+    knowledge: 0.7,
+    script: 0.6,
+    memory: 0.5,
+});
+/** Default encoding salience for types not in the table above. */
+export const DEFAULT_ENCODING_SALIENCE = 0.5;
+// ── Core computation ─────────────────────────────────────────────────────────
+/**
+ * Compute the salience vector for one asset.
+ *
+ * Pure function — no I/O. All inputs are pre-fetched by the caller.
+ */
+export function computeSalience(inputs) {
+    const now = inputs.now ?? Date.now();
+    // ── Encoding salience ────────────────────────────────────────────────────────
+    //
+    // When `inputs.encodingSalience` is provided (computed by `scoreEncodingSalience`
+    // in encoding-salience.ts at extract/distill time, #608), use it directly.
+    // Fall back to the type-importance stub only when the caller has not yet
+    // computed a content-based score (e.g. on older assets before the first
+    // staleness refresh runs).
+    const encoding = inputs.encodingSalience !== undefined
+        ? Math.min(1, Math.max(0, inputs.encodingSalience))
+        : (DEFAULT_TYPE_ENCODING_WEIGHTS[inputs.type] ?? DEFAULT_ENCODING_SALIENCE);
+    // ── Outcome salience (WS-2 active) ────────────────────────────────────────
+    //
+    // When `inputs.outcomeSalience` is provided (WS-2 has populated asset_outcome
+    // for this ref), use it directly — it has already been normalised by
+    // `outcomeScoreToSalience` in outcome-loop.ts (value in [DIVERSITY_FLOOR, 1]).
+    //
+    // When absent (new asset, no WS-2 row yet): fall back to the warm-start seed
+    // from `utilityScore` clipped to [0, WARM_START_CAP], matching the seed
+    // value that `updateAssetOutcome` writes on first row creation. This ensures
+    // `outcomeSalience` is non-zero at launch for assets with utility history
+    // (avoiding the starvation problem described in the plan §WS-2 warm start).
+    let outcome;
+    if (inputs.outcomeSalience !== undefined) {
+        // Direct pass-through — caller already normalised via outcomeScoreToSalience.
+        outcome = Math.min(1, Math.max(0, inputs.outcomeSalience));
+    }
+    else {
+        // Warm-start fallback: clip utility to [0, WARM_START_CAP] so the
+        // outcomeSalience term contributes a modest non-zero baseline.
+        outcome = Math.min(WARM_START_CAP, Math.max(0, inputs.utilityScore ?? 0));
+    }
+    // ── Retrieval salience ─────────────────────────────────────────────────────
+    //
+    // Formula: log(1 + freq) × recencyDecay
+    //   log(1+freq): sub-linear frequency term (same as proactive-maintenance prototype).
+    //   recencyDecay: 0.1 + 0.5^(useAgeDays/halflife) — decays to 0.1 floor when stale.
+    //     lastUseMs=0/undefined → useAgeDays=9999 → recencyDecay≈0.1 (floor).
+    //
+    // The recency term is MANDATORY (plan requirement §WS-1 step 2). Without it
+    // retrievalSalience degenerates to a non-decaying frequency count and the WS-3
+    // homeostatic step-0 demotion has nothing to act on.
+    const lastUseMs = inputs.lastUseMs ?? 0;
+    const useAgeDays = lastUseMs > 0 ? (now - lastUseMs) / DAY_MS : 9999;
+    const recencyDecay = 0.1 + 0.5 ** (useAgeDays / RECENCY_HALFLIFE_DAYS);
+    const rawRetrieval = Math.log(1 + inputs.retrievalFreq) * recencyDecay;
+    // ── Size penalty ─────────────────────────────────────────────────────────────
+    // 1/log10(size): larger assets are slightly deprioritized (same as proactive prototype).
+    const sizeProxy = Math.max(SIZE_FLOOR_BYTES, inputs.sizeBytes ?? 0);
+    const sizePenalty = 1 / Math.log10(sizeProxy);
+    // ── Projection → rankScore ────────────────────────────────────────────────
+    //
+    // Raw projection may be > 1 (log retrieval terms can exceed 1 for high freq + fresh use).
+    // Normalize by the theoretical maximum of the retrieval component:
+    //   max retrievalRaw = log(1 + Infinity) × (0.1 + 1.0) = Infinity, so we
+    //   cap instead — rankScore is clamped to [0,1] after applying the size penalty.
+    //
+    // Normalization approach: we scale the combined linear sum to [0,1] by clamping,
+    // after applying the size penalty. The encoding term is already in [0,1]; the
+    // retrieval term is open-ended but bounded in practice by log(1+N)×1.1 where N
+    // is the retrieval count. We normalize `retrieval` to [0,1] using a soft cap:
+    //   retrieval_normalized = rawRetrieval / (rawRetrieval + 1)
+    // which asymptotes to 1 and equals 0.5 at rawRetrieval=1. This is the same
+    // formula used for MemRL utility updates.
+    const retrieval = rawRetrieval / (rawRetrieval + 1);
+    // ── Weight selection (Part-V gate) ────────────────────────────────────────
+    //
+    // When `outcomeWeightEnabled` is false/absent (default): use WS-1 parity
+    // weights (w_e=0.30, w_r=0.70, w_o=0) so ranking is unchanged from the WS-1
+    // baseline. The `outcome` sub-score is still computed and stored in the
+    // salience vector for observability, but it does not affect rankScore.
+    //
+    // When `outcomeWeightEnabled` is true (operator opt-in after Part-V run):
+    // use WS-2 weights (w_e=0.25, w_o=0.15, w_r=0.60).
+    //
+    // The constants W_ENCODING, W_OUTCOME, W_RETRIEVAL always reflect the
+    // WS-2 target values for documentation and re-tune reference.
+    let we;
+    let wo;
+    let wr;
+    if (inputs.outcomeWeightEnabled === true) {
+        // WS-2 active: three-way split from Part-V operator opt-in.
+        we = W_ENCODING; // 0.25
+        wo = W_OUTCOME; // 0.15
+        wr = W_RETRIEVAL; // 0.60
+    }
+    else {
+        // WS-1 parity (default): w_o=0, redistribute to WS-1 proportions.
+        // Original WS-1 split was w_e=0.30, w_r=0.70.
+        we = W_ENCODING_PARITY;
+        wo = W_OUTCOME_PARITY;
+        wr = W_RETRIEVAL_PARITY;
+    }
+    const rawRankScore = (we * encoding + wo * outcome + wr * retrieval) * sizePenalty;
+    const rankScore = Math.min(1, Math.max(0, rawRankScore));
+    return { encoding, outcome, retrieval, rankScore };
+}
+/**
+ * Upsert salience scores for one asset into state.db.
+ *
+ * Idempotent: safe to call every run; updates all columns on conflict.
+ */
+export function upsertAssetSalience(db, ref, vector, now) {
+    const ts = now ?? Date.now();
+    db.prepare(`INSERT INTO asset_salience
+       (asset_ref, encoding_salience, outcome_salience, retrieval_salience, rank_score, consecutive_no_ops, updated_at)
+     VALUES (?, ?, ?, ?, ?, 0, ?)
+     ON CONFLICT(asset_ref) DO UPDATE SET
+       encoding_salience  = excluded.encoding_salience,
+       outcome_salience   = excluded.outcome_salience,
+       retrieval_salience = excluded.retrieval_salience,
+       rank_score         = excluded.rank_score,
+       updated_at         = excluded.updated_at`).run(ref, vector.encoding, vector.outcome, vector.retrieval, vector.rankScore, ts);
+}
+/**
+ * Load the salience row for one asset, or undefined if not yet computed.
+ */
+export function getAssetSalience(db, ref) {
+    const row = db
+        .prepare(`SELECT asset_ref, encoding_salience, outcome_salience, retrieval_salience,
+              rank_score, consecutive_no_ops, updated_at
+       FROM asset_salience WHERE asset_ref = ?`)
+        .get(ref);
+    // Bun SQLite returns null (not undefined) when no row found.
+    return row == null ? undefined : row;
+}
+/**
+ * Load ALL rank scores from the asset_salience table (full-stash query).
+ *
+ * Used by the forgetting-safety report (plan §WS-1 step 7) to compute stash-wide
+ * rank positions rather than pool-relative positions. Returns an empty Map when the
+ * table is empty (first WS-1 run = no pre-existing rows).
+ *
+ * Order is unspecified; callers must sort before assigning 1-indexed positions.
+ */
+export function getAllRankScores(db) {
+    const rows = db.prepare("SELECT asset_ref, rank_score FROM asset_salience").all();
+    const result = new Map();
+    for (const row of rows) {
+        result.set(row.asset_ref, row.rank_score);
+    }
+    return result;
+}
+// ── Plasticity helpers ────────────────────────────────────────────────────────
+/**
+ * Increment `consecutive_no_ops` for an asset. Called after a no-op reflect/distill.
+ * Has NO effect on `rank_score` — the plasticity counter only dampens consolidation
+ * selection, not retrieval ranking. See plan §WS-1 step 8.
+ *
+ * Invariant: recordNoOp must never originate rank_score semantics. If the asset has
+ * no salience row yet (persistence's best-effort try/catch may have swallowed an
+ * error), we do nothing — a no-op counter is meaningless without a rank_score row,
+ * and a synthetic INSERT would fabricate a rank_score=0 entry that could produce
+ * false catastrophic-forgetting signals in buildRankChangeReport.
+ */
+export function recordNoOp(db, ref) {
+    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = consecutive_no_ops + 1, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
+    // If changes === 0 the asset has no salience row yet — leave the table unchanged.
+}
+/**
+ * Reset `consecutive_no_ops` to 0 when an asset produces an accepted change.
+ * Call after a successful proposal acceptance or detected mutation.
+ */
+export function resetConsecutiveNoOps(db, ref) {
+    db.prepare(`UPDATE asset_salience SET consecutive_no_ops = 0, updated_at = ? WHERE asset_ref = ?`).run(Date.now(), ref);
+}
+/**
+ * Return the `consecutive_no_ops` count for one asset. 0 when unknown.
+ */
+export function getConsecutiveNoOps(db, ref) {
+    const row = db.prepare(`SELECT consecutive_no_ops FROM asset_salience WHERE asset_ref = ?`).get(ref);
+    return row?.consecutive_no_ops ?? 0;
+}
+// ── Consolidation-selection dampener constants ────────────────────────────────
+//
+// Assets with consecutive_no_ops >= THRESHOLD are deprioritised in the
+// SELECTION ORDER only. The persisted rank_score is intentionally left
+// unchanged so stable assets remain fully retrievable by other callers.
+//
+// Tuning guidance:
+//   THRESHOLD — how many consecutive no-op runs before dampening kicks in.
+//               3 means "skipped three times in a row", which signals the
+//               LLM consistently has nothing to say about this asset.
+//   FACTOR    — multiplicative penalty on the effective selection score.
+//               0.5 halves the apparent score so a dampened asset sorts
+//               after any peer with >= half its rankScore.
+export const SALIENCE_NO_OP_DAMPEN_THRESHOLD = 3;
+export const SALIENCE_NO_OP_DAMPEN_FACTOR = 0.5;
+/**
+ * Emit the forgetting-safety rank-change distribution report.
+ *
+ * Compares the provided `newRanks` (Map<ref, position (1-indexed)>) against
+ * the provided `oldRanks` and flags refs that were in the old top-200 but
+ * are now below position 500 as "forgetting candidates".
+ *
+ * Caller is responsible for computing old/new rank positions before and after
+ * the WS-1 formula cutover. Called once at cutover, not every run.
+ *
+ * @param oldRanks - Map<ref, 1-indexed rank position> under the OLD formula.
+ * @param newRanks - Map<ref, 1-indexed rank position> under the NEW formula.
+ * @param oldTopN  - Assets in old top-N to guard (default: 200).
+ * @param forgettingThreshold - New rank position below which a fall is flagged (default: 500).
+ */
+export function buildRankChangeReport(oldRanks, newRanks, oldTopN = 200, forgettingThreshold = 500) {
+    const allChanges = [];
+    const forgettingCandidates = [];
+    for (const [ref, oldRank] of oldRanks) {
+        const newRank = newRanks.get(ref);
+        if (newRank === undefined)
+            continue; // ref not in new ranking
+        const rankDelta = newRank - oldRank; // positive = fell in rank
+        allChanges.push({ ref, oldRank, newRank, rankDelta });
+        if (oldRank <= oldTopN && newRank > forgettingThreshold) {
+            forgettingCandidates.push({ ref, oldRank, newRank, rankDelta });
+        }
+    }
+    // Sort by magnitude of rank drop (most dramatic first).
+    forgettingCandidates.sort((a, b) => b.rankDelta - a.rankDelta);
+    return { forgettingCandidates, allChanges };
+}
+// ── Last-use timestamp lookup helper ─────────────────────────────────────────
+//
+// Wraps the index DB query to retrieve the last-retrieval timestamp per ref,
+// so callers do not need to import the raw db helpers directly. Returns a Map
+// keyed by the same ref strings passed in.
+//
+// Source: `utility_scores.last_used_at` (ISO-8601 string) joined to entries
+// via entry_id. WS-2 may later supersede this with `asset_outcome.last_retrieved_at`.
+/**
+ * Build a Map<ref, lastUseMs> from the index database's utility_scores table.
+ *
+ * Returns only refs that have a non-null `last_used_at`. Refs absent from the
+ * map should be treated as never retrieved (lastUseMs = 0).
+ *
+ * @param indexDb - An open read-capable index database connection.
+ * @param refs    - The set of asset refs to look up.
+ */
+export function getLastUseMsByRef(indexDb, refs) {
+    const result = new Map();
+    if (refs.length === 0)
+        return result;
+    const refSet = new Set(refs);
+    const allEntries = getAllEntries(indexDb);
+    const idToRef = new Map();
+    for (const indexed of allEntries) {
+        const ref = makeAssetRef(indexed.entry.type, indexed.entry.name);
+        if (refSet.has(ref))
+            idToRef.set(indexed.id, ref);
+    }
+    const ids = [...idToRef.keys()];
+    if (ids.length === 0)
+        return result;
+    const { global: scores } = getUtilityScoresByIds(indexDb, ids);
+    for (const [id, row] of scores) {
+        const ref = idToRef.get(id);
+        if (!ref)
+            continue;
+        const lastUsedAt = row.lastUsedAt;
+        if (!lastUsedAt)
+            continue;
+        const ms = typeof lastUsedAt === "number" ? lastUsedAt : Date.parse(lastUsedAt);
+        if (ms > 0)
+            result.set(ref, ms);
+    }
+    return result;
+}

package/dist/commands/improve/triage.js

@@ -0,0 +1,95 @@
+// 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/.
+/**
+ * Default minimum total score a session must reach to PASS the gate. Tuned
+ * conservatively: a single real narrative-lesson session, or a procedurally
+ * dense session, clears it — but pure read-only Q&A does not. Config-overridable
+ * via `processes.extract.triage.minScore`.
+ */
+export const DEFAULT_TRIAGE_MIN_SCORE = 2;
+// Decision / outcome / error narrative markers. Case-insensitive, word-bounded.
+const MARKER_RE = /\b(error|failed|fix(?:ed)?|root cause|turns out|because|decided|instead|gotcha|workaround|regress(?:ed)?|broke|TIL)\b/i;
+// Edit / commit / file-write markers in tool event text.
+const EDIT_COMMIT_RE = /\b(Edit|Write|MultiEdit|git commit|diff)\b/i;
+// A substantive turn is an assistant or tool turn whose text is non-trivial.
+const SUBSTANTIVE_MIN_CHARS = 40;
+/**
+ * Pure heuristic scorer. Operates only on `data.events`. Each sub-signal is
+ * normalized to a small bounded contribution; `score` is their sum and
+ * `pass = score >= minScore`.
+ *
+ * Sub-signals:
+ *   - markers: presence of decision/outcome/error keywords across event text
+ *     (capped, narrative-lesson signal).
+ *   - toolDensity: bounded contribution from tool-use events (procedural).
+ *   - editCommit: bounded contribution from edit/write/commit events (procedural).
+ *   - substantiveRatio: scaled fraction of non-trivial assistant+tool turns,
+ *     filtering pure short Q&A.
+ *
+ * The procedural sub-signals (toolDensity + editCommit) alone can clear
+ * DEFAULT_TRIAGE_MIN_SCORE so high-action / no-narrative sessions are KEPT (#615).
+ */
+export function scoreSessionTriage(data, minScore) {
+    const events = data.events;
+    const total = events.length;
+    // (a) markers — count word-bounded marker hits across all event text, capped.
+    let markerHits = 0;
+    for (const e of events) {
+        if (MARKER_RE.test(e.text))
+            markerHits += 1;
+    }
+    // Each marker-bearing event contributes 1 point, capped at 2 (a single real
+    // narrative session clears the bar on markers alone).
+    const markers = Math.min(markerHits, 2);
+    // (b) toolDensity — bounded contribution from tool-use events.
+    let toolEvents = 0;
+    for (const e of events) {
+        if (e.role === "tool")
+            toolEvents += 1;
+    }
+    // 0.25 per tool event, capped at 1.5.
+    const toolDensity = Math.min(toolEvents * 0.25, 1.5);
+    // (c) editCommit — bounded contribution from edit/write/commit markers on
+    // events (filePath present, or text matching the edit/commit regex).
+    let editCommitEvents = 0;
+    for (const e of events) {
+        if (e.filePath || EDIT_COMMIT_RE.test(e.text))
+            editCommitEvents += 1;
+    }
+    // 0.25 per edit/commit event, capped at 1.5. Together with toolDensity a
+    // procedurally dense session reaches well above the default threshold.
+    const editCommit = Math.min(editCommitEvents * 0.25, 1.5);
+    // (d) substantiveRatio — scaled fraction of non-trivial assistant+tool turns.
+    let substantive = 0;
+    for (const e of events) {
+        if ((e.role === "assistant" || e.role === "tool") && e.text.length >= SUBSTANTIVE_MIN_CHARS) {
+            substantive += 1;
+        }
+    }
+    const ratio = total > 0 ? substantive / total : 0;
+    // Scale to a bounded [0,1] contribution.
+    const substantiveRatio = Math.min(ratio, 1);
+    const subscores = { markers, toolDensity, editCommit, substantiveRatio };
+    const score = markers + toolDensity + editCommit + substantiveRatio;
+    const pass = score >= minScore;
+    return {
+        pass,
+        score,
+        subscores,
+        ...(pass ? {} : { reason: "low_signal" }),
+    };
+}
+/**
+ * Resolve the effective triage config from the extract process config. Mirrors
+ * the minContentChars / schemaSimilarity resolution style in akmExtract.
+ *
+ * Default-off: `enabled` is FALSE unless `triage.enabled === true`. `minScore`
+ * defaults to {@link DEFAULT_TRIAGE_MIN_SCORE}.
+ */
+export function resolveTriageConfig(extractProcess) {
+    const triage = extractProcess?.triage;
+    const enabled = triage?.enabled === true;
+    const minScore = typeof triage?.minScore === "number" ? triage.minScore : DEFAULT_TRIAGE_MIN_SCORE;
+    return { enabled, minScore };
+}

package/dist/commands/lint/agent-linter.js

@@ -1,22 +1,25 @@
 // 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 path from "node:path";
 import { BaseLinter } from "./base-linter.js";
+/** Valid values for the `type` field in agent frontmatter. */
+const VALID_AGENT_TYPES = ["agent"];
 /**
  * Linter for `agents/` assets.
  *
- * Extra check beyond base:
+ * Extra checks beyond base:
  *   - `missing-name-or-type`: frontmatter exists but `name` or `type` field is
  *     absent. Not auto-fixable; detail includes a suggested slug.
+ *   - `missing-name-or-type` (invalid value): `type` is present but not a
+ *     recognised agent type value.
  */
 export class AgentLinter extends BaseLinter {
     types = ["agents"];
     lint(ctx) {
         const issues = this.runBaseChecks(ctx);
-        const missingFieldDetail = this.#checkMissingNameOrType(ctx.data, ctx.frontmatter);
+        const missingFieldDetail = this.checkMissingNameOrType(ctx.data, ctx.frontmatter);
         if (missingFieldDetail) {
-            const slug = this.#suggestSlug(ctx.filePath);
+            const slug = this.suggestSlug(ctx.filePath);
             issues.push({
                 file: ctx.relPath,
                 issue: "missing-name-or-type",
@@ -24,26 +27,18 @@ export class AgentLinter extends BaseLinter {
                 fixed: false,
             });
         }
+        else {
+            // Only validate the value when the field is actually present.
+            const invalidTypeDetail = this.checkInvalidTypeValue(ctx.data, VALID_AGENT_TYPES);
+            if (invalidTypeDetail) {
+                issues.push({
+                    file: ctx.relPath,
+                    issue: "missing-name-or-type",
+                    detail: invalidTypeDetail,
+                    fixed: false,
+                });
+            }
+        }
         return issues;
     }
-    #checkMissingNameOrType(data, frontmatterText) {
-        if (!frontmatterText)
-            return null;
-        const missingFields = [];
-        if (!("name" in data) || !data.name)
-            missingFields.push("name");
-        if (!("type" in data) || !data.type)
-            missingFields.push("type");
-        if (missingFields.length === 0)
-            return null;
-        return `missing fields: ${missingFields.join(", ")}`;
-    }
-    #suggestSlug(filePath) {
-        return path
-            .basename(filePath, ".md")
-            .toLowerCase()
-            .replace(/[^a-z0-9-]+/g, "-")
-            .replace(/-+/g, "-")
-            .replace(/^-|-$/g, "");
-    }
 }