claude-mem-lite 3.10.0 → 3.12.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "claude-mem-lite",
-      "version": "3.10.0",
+      "version": "3.12.0",
       "source": "./",
       "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark)."
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "author": {
     "name": "sdsrss"

package/hook.mjs

@@ -58,6 +58,7 @@ import {
 } from './lib/citation-tracker.mjs';
 import { extractTailAssistantText, extractStructuredSummary } from './lib/summary-extractor.mjs';
 import { searchRelevantMemories, formatMemoryLine } from './hook-memory.mjs';
+import { recordSkillAdoption } from './registry-recommend.mjs';
 import { detectMemOverride } from './lib/mem-override.mjs';
 import { buildAndSaveHandoff, detectContinuationIntent, renderHandoffInjection, pickHandoffToInject, extractUnfinishedSummary } from './hook-handoff.mjs';
 import { checkForUpdate, getCachedUpdateBanner, isUpdateCheckDue } from './hook-update.mjs';
@@ -257,6 +258,16 @@ async function handlePostToolUse() {
   if (SKIP_TOOLS.has(tool_name)) return;
   if (SKIP_PREFIXES.some(p => tool_name.startsWith(p))) return;
 
+  // Shadow skill-adoption telemetry. mem_use is pre-filtered above, so the Skill tool is
+  // the only visible adoption signal (v1). Placed before the resp-length gate because a
+  // skill load's response shape varies. Never throws.
+  if (tool_name === 'Skill') {
+    const ti = typeof tool_input === 'string' ? tryParseJson(tool_input) : (tool_input || {});
+    // hookData.session_id (CC UUID) pairs this adoption to the would-be reco from the
+    // UserPromptSubmit hook earlier in the same session (matched precision, B1).
+    try { recordSkillAdoption('Skill', ti, inferProject(), hookData.session_id); } catch {}
+  }
+
   const resp = normalizeToolResponse(tool_response);
   if (!resp || resp.length < 10) return;
 

package/lib/import-jsonl.mjs

@@ -163,6 +163,12 @@ export async function importJsonl(db, path, { project }) {
 
   const pendingToolUse = new Map();
   let prompts = 0, observations = 0, skipped = 0;
+  // Count lines that ARE Claude Code transcript events (user/assistant/tool_result),
+  // independent of whether they produced a new row. Lets the caller tell apart a
+  // genuine wrong-shape file (export output / garbage → recognized 0) from a valid
+  // transcript that was simply already imported (recognized > 0, all deduped) — the
+  // "0 imported, N skipped" warning must not cry "wrong shape" at an idempotent re-run.
+  let recognized = 0;
 
   // Snapshot importToolPair so we can wrap it with a per-run uniqueness
   // check that hits both in-call and cross-call dedup. (Inline because we
@@ -193,6 +199,8 @@ export async function importJsonl(db, path, { project }) {
       if (!line.trim()) continue;
       const ev = parseLine(line);
       if (!ev) { skipped++; continue; }
+      // Transcript-shape signal (incl. embedded + top-level tool_result, #8413).
+      if (ev.type === 'user' || ev.type === 'assistant' || ev.type === 'tool_result') recognized++;
       if (ev.type === 'user') {
         // Real Claude Code transcripts wrap tool_result inside a user-typed
         // event's message.content array (alongside the rare text part). The
@@ -256,5 +264,5 @@ export async function importJsonl(db, path, { project }) {
     tx2();
   }
 
-  return { prompts, observations, skipped, orphans };
+  return { prompts, observations, skipped, orphans, recognized };
 }

package/lib/maintain-core.mjs

@@ -301,7 +301,12 @@ export function maintenanceStats(db, { projectFilter, baseParams, staleAge }) {
   const stats = db.prepare(`
     SELECT
       COUNT(*) as total,
+      -- injection_count=0 MUST mirror decayAndMarkIdle's mark-idle guard (#8614):
+      -- the scan stat previews what decay will mark idle, and decay protects
+      -- injected rows. Omitting it over-counted "stale" by the injected-but-decayed
+      -- rows decay never touches (e.g. demote_pinned's output: imp=1 but inj>0).
       COALESCE(SUM(CASE WHEN COALESCE(importance, 1) = 1 AND COALESCE(access_count, 0) = 0
+                    AND COALESCE(injection_count, 0) = 0
                     AND created_at_epoch < ? THEN 1 ELSE 0 END), 0) as stale,
       COALESCE(SUM(CASE WHEN (title IS NULL OR title = '') AND (narrative IS NULL OR narrative = '')
                THEN 1 ELSE 0 END), 0) as broken,

package/mem-cli.mjs

@@ -13,6 +13,7 @@ import { searchObservationsHybrid } from './search-engine.mjs';
 import { deepSearch, resolveDeepMode, shouldEscalateToDeep, autoDeepLlmReady } from './deep-search.mjs';
 import { ensureRegistryDb, upsertResource } from './registry.mjs';
 import { searchResources } from './registry-retriever.mjs';
+import { computeFunnel, formatFunnel, computeSweep, formatSweep, DEFAULT_SWEEP_FLOORS, DEFAULT_SWEEP_MARGINS } from './registry-recommend.mjs';
 import { selectCompressionCandidates, groupByProjectWeek, compressGroup } from './lib/compress-core.mjs';
 import {
   cleanupBroken, decayAndMarkIdle, boostAccessed, demotePinned, mergeDuplicates,
@@ -308,18 +309,26 @@ function cmdRecent(db, args) {
   const { positional, flags } = parseArgs(args);
   const rawArg = positional[0];
   const rawLimit = parseInt(rawArg, 10);
+  // Single source of the upper bound for BOTH the positional [N] and the --limit
+  // flag (help: "alias for [N] (max 1000)"). Pre-fix the positional path skipped
+  // this cap, so `recent 999999` issued an uncapped `LIMIT 999999` full-table dump
+  // while `recent --limit 999999` correctly rejected → default — exactly the
+  // "none capped --limit dumps the whole set" footgun parseIntFlag was extracted
+  // to close (lib/cli-flags.mjs). Keep the literal in one place so the two paths
+  // can't drift apart again.
+  const RECENT_MAX = 1000;
   // isNumericToken first: "2abc"→2 / "1e2"→1 are positive integers that the bare check
   // accepted silently; the positional path must reject garbage like the --limit flag does.
-  const isValid = rawArg !== undefined && isNumericToken(rawArg) && Number.isInteger(rawLimit) && rawLimit > 0;
+  const isValid = rawArg !== undefined && isNumericToken(rawArg) && Number.isInteger(rawLimit) && rawLimit > 0 && rawLimit <= RECENT_MAX;
   if (rawArg !== undefined && !isValid) {
-    process.stderr.write(`[mem] Invalid count "${rawArg}" (must be a positive integer); using default 10\n`);
+    process.stderr.write(`[mem] Invalid count "${rawArg}" (must be an integer between 1 and ${RECENT_MAX}); using default 10\n`);
   }
   // Positional [N] wins for backward-compat; --limit is sibling-parity alias
   // (search/recall/browse/stats all accept --limit). Pre-2.69 `recent --limit N`
   // was silently ignored — surprising users extrapolating from siblings.
   const limit = isValid
     ? rawLimit
-    : parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: 1000 });
+    : parseIntFlag(flags.limit, { name: '--limit', defaultValue: 10, max: RECENT_MAX });
   const project = flags.project ? resolveProject(db, flags.project) : inferProject();
   const jsonOutput = flags.json === true || flags.json === 'true';
 
@@ -1768,7 +1777,7 @@ function cmdMaintain(db, args) {
     out(`[mem] Maintenance scan:`);
     out(`  Total active: ${stats.total}`);
     out(`  Near-duplicate pairs: ${duplicates.length}`);
-    out(`  Stale (>30d, imp=1, no access): ${stats.stale}`);
+    out(`  Stale (>30d, imp=1, no access, never injected): ${stats.stale}`);
     out(`  Broken (no title/narrative): ${stats.broken}`);
     out(`  Boostable (accessed>3, imp<3): ${stats.boostable}`);
     out(`  Pinned-but-uncited (inj>=${PINNED_INJ_THRESHOLD}, cited=0, imp>1): ${stats.pinned} — run: maintain execute --ops demote_pinned`);
@@ -1933,8 +1942,29 @@ import { cmdFtsCheck } from './cli/fts-check.mjs';
 function cmdRegistry(_memDb, args) {
   const { positional, flags } = parseArgs(args);
   const action = positional[0];
-  if (!action || !['list', 'stats', 'search', 'import', 'remove', 'reindex'].includes(action)) {
-    fail('[mem] Usage: claude-mem-lite registry <list|stats|search|import|remove|reindex> [--type skill|agent] [--query Q] [--name N] [--resource-type T]');
+  if (!action || !['list', 'stats', 'search', 'import', 'remove', 'reindex', 'recommend-stats'].includes(action)) {
+    fail('[mem] Usage: claude-mem-lite registry <list|stats|search|import|remove|reindex|recommend-stats> [--type skill|agent] [--query Q] [--name N] [--resource-type T]');
+    return;
+  }
+
+  // recommend-stats reads the shadow-recommendation JSONL (filesystem), not the
+  // registry DB — handle it before opening rdb so it works without a registry DB.
+  if (action === 'recommend-stats') {
+    const days = (typeof flags.days === 'string' || typeof flags.days === 'number') && +flags.days > 0 ? Math.floor(+flags.days) : 7;
+    out(formatFunnel(computeFunnel(days)));
+    if (flags.sweep) {
+      // Offline ROC over the shipped gate thresholds (B3). Parse `--floors`/`--margins` as
+      // comma lists of finite numbers; fall back to the spanning defaults on bad/empty input.
+      const parseNums = (v, fallback) => {
+        if (typeof v !== 'string') return fallback;
+        const nums = v.split(',').map(x => Number(x.trim())).filter(Number.isFinite);
+        return nums.length ? nums : fallback;
+      };
+      const floors = parseNums(flags.floors, DEFAULT_SWEEP_FLOORS);
+      const margins = parseNums(flags.margins, DEFAULT_SWEEP_MARGINS);
+      out('');
+      out(formatSweep(computeSweep(days, floors, margins)));
+    }
     return;
   }
 
@@ -2585,7 +2615,7 @@ async function cmdImportJsonl(db, argv) {
   if (files.length === 0) { out('[mem] No .jsonl files found.'); return; }
 
   const { importJsonl } = await import('./lib/import-jsonl.mjs');
-  let totalPrompts = 0, totalObs = 0, totalSkip = 0, totalOrphans = 0, errorCount = 0;
+  let totalPrompts = 0, totalObs = 0, totalSkip = 0, totalOrphans = 0, totalRecognized = 0, errorCount = 0;
   for (const f of files) {
     // Per-file isolation: one unreadable file (EACCES, EBUSY, mid-batch IO error)
     // shouldn't crash the whole import — readFileSync inside importJsonl would
@@ -2605,18 +2635,29 @@ async function cmdImportJsonl(db, argv) {
     totalObs += r.observations;
     totalSkip += r.skipped;
     totalOrphans += r.orphans || 0;
+    totalRecognized += r.recognized || 0;
     out(`[mem] ${f}: +${r.prompts} prompts, +${r.observations} observations, ${r.orphans || 0} orphan tool_use, ${r.skipped} skipped`);
   }
   const errorTail = errorCount > 0 ? `, ${errorCount} file(s) errored` : '';
   out(`[mem] Total: ${totalPrompts} prompts, ${totalObs} observations, ${totalOrphans} orphan tool_use, ${totalSkip} skipped from ${files.length} file(s)${errorTail}.`);
-  if (totalPrompts > 0 || totalObs > 0) {
+  if (totalPrompts > 0 || totalObs > 0 || totalOrphans > 0) {
+    // Orphan tool_use events persist as (truncated) observations, so they count as
+    // "something was imported" — otherwise an orphan-only first import would wrongly
+    // fall through to the "already imported" no-op branch below.
     out(`[mem] Try: claude-mem-lite recent 5 --project ${project}`);
+  } else if (totalRecognized > 0) {
+    // Lines WERE Claude Code transcript events but produced no new rows — the file
+    // was already imported (idempotent re-run) or carried no extractable content.
+    // Distinct from the wrong-shape case below: do NOT cry "wrong shape" at a valid
+    // transcript the user successfully imported earlier (cold-start backfill re-runs
+    // hit this on every already-ingested file).
+    out(`[mem] Nothing new: ${totalRecognized} transcript event(s) already imported (re-running import-jsonl on the same transcript is a safe no-op).`);
   } else if (totalSkip > 0 && errorCount === 0) {
-    // Nothing imported but every line was skipped — almost always the wrong file
-    // format (import-jsonl ingests Claude Code transcript JSONL, not `export` output,
-    // which is observation-shaped). Pre-fix this exited 0 with no signal, so pointing
-    // it at the wrong file looked like success. Make the no-op explicit (stdout, like
-    // the summary lines above).
+    // No transcript event recognized at all — almost always the wrong file format
+    // (import-jsonl ingests Claude Code transcript JSONL, not `export` output, which
+    // is observation-shaped). Pre-fix this exited 0 with no signal, so pointing it at
+    // the wrong file looked like success. Make the no-op explicit (stdout, like the
+    // summary lines above).
     out(`[mem] Warning: 0 imported, ${totalSkip} line(s) skipped — none matched the expected Claude Code transcript JSONL shape (user/assistant/tool_result). 'export' output is NOT re-importable via import-jsonl.`);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-mem-lite",
-  "version": "3.10.0",
+  "version": "3.12.0",
   "description": "Persistent long-term memory for Claude Code via MCP — captures coding decisions, bugfixes, and context across sessions. Hybrid FTS5 + TF-IDF search with episode batching. Single SQLite DB, no external services. A lighter, lower-cost alternative to claude-mem (episode batching + a smaller model; cost savings are an internal estimate, not a measured benchmark).",
   "type": "module",
   "packageManager": "npm@10.9.2",
@@ -95,6 +95,7 @@
     "server/fts-check.mjs",
     "registry.mjs",
     "registry-retriever.mjs",
+    "registry-recommend.mjs",
     "registry-indexer.mjs",
     "registry-scanner.mjs",
     "registry-github.mjs",

package/registry-recommend.mjs

@@ -0,0 +1,301 @@
+// Intent-based skill recommendation — Phase 1 (shadow).
+// See docs/superpowers/specs/2026-06-23-skill-recommendation-loop-design.md
+//
+// Phase-1 invariant: shadow AND live only LOG. Neither emits to stdout nor writes
+// invocations/recommend_count. Live injection is Phase 2. `off` skips all work.
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, appendFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { searchResources, cjkIntentTokens } from './registry-retriever.mjs';
+
+const VALID_MODES = new Set(['shadow', 'live', 'off']);
+
+/** Recommendation mode from env; default 'shadow', unknown → 'shadow'. */
+export function getRecommendMode() {
+  const raw = (process.env.CLAUDE_MEM_RECOMMEND_MODE || 'shadow').toLowerCase().trim();
+  return VALID_MODES.has(raw) ? raw : 'shadow';
+}
+
+// Provisional gate thresholds — calibrated from shadow data before Phase 2 (spec §8).
+// relevance is raw bm25 (negative; more negative = better). Candidate must clear |floor|.
+export const RECO_BM25_FLOOR = -1.5;     // require row.relevance <= -1.5
+export const RECO_MARGIN = 0.5;          // require candidates[1].relevance - candidates[0].relevance >= 0.5
+const RECO_COOLDOWN_MS = 300_000;        // 5 min, mirrors T4 SKILL_COOLDOWN_MS (internal)
+
+// Lazy runtime-path resolution: read CLAUDE_MEM_DIR at call time (mirrors schema.mjs:13
+// DB_DIR formula) so tests sandbox via env without ESM-cache gymnastics, and prod reads
+// the same dir as the rest of the app.
+function recoRuntimeDir() {
+  return join(process.env.CLAUDE_MEM_DIR || join(homedir(), '.claude-mem-lite'), 'runtime');
+}
+
+const TOKEN_SPLIT = /[^a-z0-9一-鿿]+/;
+
+/** Installed skills (quality_tier='installed') matching the prompt, best-first. */
+export function fetchInstalledSkillCandidates(rdb, promptText, limit = 10) {
+  if (!rdb || !promptText) return [];
+  let rows;
+  try { rows = searchResources(rdb, promptText, { type: 'skill', limit }); }
+  catch { return []; }
+  return rows.filter(r => r.quality_tier === 'installed');
+}
+
+/**
+ * True when an intent tag matches a prompt token. Tags of length >= 3 match as a token
+ * PREFIX (plural/inflection tolerant: "test" → "tests"/"testing"; rejects mid-word hits
+ * like "latest"); shorter tags ("qa","go","db") require an exact token to avoid noise.
+ */
+export function intentMatch(promptText, candidate) {
+  const tags = String(candidate.intent_tags || '').toLowerCase().split(/[,\s]+/).filter(Boolean);
+  if (tags.length === 0) return false;
+  const tokens = String(promptText).toLowerCase().split(TOKEN_SPLIT).filter(Boolean);
+  // CJK bridge: intent_tags are English, but Chinese has no word boundaries, so a pure-中文
+  // prompt ("写测试") tokenizes to one CJK run that never prefix-matches "test". Inject the
+  // English equivalents of any CJK_INTENT_MAP phrase present so 中文 prompts can clear gate 3.
+  for (const en of cjkIntentTokens(promptText)) tokens.push(en);
+  return tags.some(tag => tokens.some(tok => (tag.length >= 3 ? tok.startsWith(tag) : tok === tag)));
+}
+
+/**
+ * 4-gate precision filter. relevance is raw bm25 (negative; more negative = better).
+ * Gates in order: absolute floor → top1/top2 margin → intent token match → session cooldown.
+ */
+export function applyGate(candidates, promptText, cooldownSet) {
+  if (!candidates || candidates.length === 0) return { verdict: 'BLOCK', reason: 'no_candidate', candidate: null };
+  const top = candidates[0];
+  if (!(top.relevance <= RECO_BM25_FLOOR)) return { verdict: 'BLOCK', reason: 'below_floor', candidate: top };
+  if (candidates.length >= 2) {
+    const margin = candidates[1].relevance - top.relevance; // positive when top is clearly better
+    if (!(margin >= RECO_MARGIN)) return { verdict: 'BLOCK', reason: 'low_margin', candidate: top };
+  }
+  if (!intentMatch(promptText, top)) return { verdict: 'BLOCK', reason: 'intent_mismatch', candidate: top };
+  if (cooldownSet && cooldownSet.has(String(top.name).toLowerCase())) return { verdict: 'BLOCK', reason: 'cooldown', candidate: top };
+  return { verdict: 'PASS', reason: 'pass', candidate: top };
+}
+
+function recoCooldownFile(project) { return join(recoRuntimeDir(), `.skill-reco-cooldown-${project}`); }
+
+/** Read live (non-expired) cooldown entries for a project: {nameLower: epochMs}. */
+export function getRecoCooldown(project) {
+  try {
+    const data = JSON.parse(readFileSync(recoCooldownFile(project), 'utf8'));
+    const now = Date.now(); const cleaned = {};
+    for (const [k, v] of Object.entries(data)) if (now - v < RECO_COOLDOWN_MS) cleaned[k] = v;
+    return cleaned;
+  } catch { return {}; }
+}
+
+/** Stamp a skill name into the project's cooldown (atomic tmp+rename, mirrors T4). */
+export function setRecoCooldown(project, name) {
+  try {
+    const dir = recoRuntimeDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const data = getRecoCooldown(project);
+    data[String(name).toLowerCase()] = Date.now();
+    const tmp = recoCooldownFile(project) + `.tmp-${process.pid}`;
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, recoCooldownFile(project));
+  } catch { /* silent — cooldown best-effort */ }
+}
+
+function today() { return new Date().toISOString().slice(0, 10); }
+function shadowDir() { return join(recoRuntimeDir(), 'recommendations'); }
+
+function appendShadow(row) {
+  try {
+    const dir = shadowDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    appendFileSync(join(dir, `${today()}.jsonl`), JSON.stringify(row) + '\n', { mode: 0o600 });
+  } catch { /* shadow sink must never crash the hook */ }
+}
+
+export function logShadowReco(project, rec) { appendShadow({ ts: new Date().toISOString(), kind: 'reco', project, ...rec }); }
+export function logShadowAdoption(project, rec) { appendShadow({ ts: new Date().toISOString(), kind: 'adopt', project, ...rec }); }
+
+/** Yield parsed shadow rows from the last `days` daily shards. */
+export function* readShadowLog(days = 7) {
+  for (let i = 0; i < days; i++) {
+    const d = new Date(Date.now() - i * 86_400_000).toISOString().slice(0, 10);
+    let raw;
+    try { raw = readFileSync(join(shadowDir(), `${d}.jsonl`), 'utf8'); } catch { continue; }
+    for (const line of raw.split('\n')) { if (!line) continue; try { yield JSON.parse(line); } catch { /* skip malformed */ } }
+  }
+}
+
+const lc = (s) => String(s ?? '').toLowerCase();
+
+/**
+ * Aggregate the would-be funnel for the flip decision (spec §8).
+ *
+ * Coarse global counts (reco/pass/blockByReason/adopt/passSkills/adoptSkills) are kept for
+ * back-compat. The flip-decision metrics live under `matched`/`lift`/`sessions`:
+ *  - matched: in-session PASS→adopt pairing (true matched precision, not a global name join).
+ *  - lift[skill]: P(adopt | gate PASSed it this session) / base-rate(adopt). >1 means the gate
+ *    beats the skill's organic base rate — the only popularity-robust evidence the gate has
+ *    targeting signal. Null-session rows can't be paired, so they feed only the coarse counts.
+ */
+export function computeFunnel(days = 7) {
+  const stats = { reco: 0, pass: 0, blockByReason: {}, adopt: 0, passSkills: {}, adoptSkills: {} };
+  const bump = (obj, k) => { if (k) obj[k] = (obj[k] || 0) + 1; };
+  const bySession = new Map();
+  const sess = (id) => { let e = bySession.get(id); if (!e) { e = { pass: new Set(), adopt: new Set() }; bySession.set(id, e); } return e; };
+  for (const row of readShadowLog(days)) {
+    if (row.kind === 'reco') {
+      stats.reco++;
+      if (row.verdict === 'PASS') { stats.pass++; bump(stats.passSkills, row.skill); if (row.session) sess(row.session).pass.add(lc(row.skill)); }
+      else bump(stats.blockByReason, row.reason);
+    } else if (row.kind === 'adopt') {
+      stats.adopt++; bump(stats.adoptSkills, row.skill);
+      if (row.session) sess(row.session).adopt.add(lc(row.skill));
+    }
+  }
+  stats.sessions = bySession.size;
+  let mPass = 0, mAdopt = 0;
+  const passSessions = {}, hitSessions = {}, baseSessions = {};
+  for (const { pass, adopt } of bySession.values()) {
+    for (const sk of pass) { mPass++; passSessions[sk] = (passSessions[sk] || 0) + 1; if (adopt.has(sk)) { mAdopt++; hitSessions[sk] = (hitSessions[sk] || 0) + 1; } }
+    for (const sk of adopt) baseSessions[sk] = (baseSessions[sk] || 0) + 1;
+  }
+  stats.matched = { pass: mPass, adopt: mAdopt, precision: mPass ? mAdopt / mPass : null };
+  stats.lift = {};
+  for (const sk of Object.keys(passSessions)) {
+    const ps = passSessions[sk], hs = hitSessions[sk] || 0;
+    const baseRate = stats.sessions ? (baseSessions[sk] || 0) / stats.sessions : 0;
+    const adoptGivenPass = ps ? hs / ps : 0;
+    stats.lift[sk] = { passSessions: ps, hitSessions: hs, adoptGivenPass, baseRate, lift: baseRate > 0 ? adoptGivenPass / baseRate : null };
+  }
+  return stats;
+}
+
+// Default sweep grid (B3). Raw BM25 magnitudes for real matches run ≈ -10..-15, so the
+// shipped floor (-1.5) is far more permissive than it looks; the grid spans that real range
+// so the ROC curve actually moves. Override via `recommend-stats --sweep --floors a,b --margins x,y`.
+export const DEFAULT_SWEEP_FLOORS = [-1.5, -5, -8, -10, -12];
+export const DEFAULT_SWEEP_MARGINS = [0, 0.5, 1, 2, 4];
+
+/**
+ * Recompute the gate verdict for a logged reco row at a hypothetical (floor, margin),
+ * from its eager replay vector (relevance/rel2/intentTop/cooldownTop). Pure — no retrieval.
+ * intent/cooldown are fixed pass/block bits; only floor and margin are swept.
+ */
+export function replayGate(row, floor, margin) {
+  const r1 = row.relevance;
+  // null/undefined relevance coerces to 0/NaN, so `r1 <= floor` is false → BLOCK (no null check).
+  if (!(r1 <= floor)) return 'BLOCK';
+  if (Number.isFinite(row.rel2) && !((row.rel2 - r1) >= margin)) return 'BLOCK';
+  if (!row.intentTop) return 'BLOCK';
+  if (row.cooldownTop) return 'BLOCK';
+  return 'PASS';
+}
+
+/**
+ * Offline ROC sweep (B3): replay every reco row at each (floor × margin) and join the would-be
+ * PASSes with in-session adoptions for matched precision. Turns the flip decision from one
+ * underpowered point estimate into a precision/recall curve over collected shadow data (spec §8).
+ */
+export function computeSweep(days = 7, floors = DEFAULT_SWEEP_FLOORS, margins = DEFAULT_SWEEP_MARGINS) {
+  const recos = [];
+  const adoptBySession = new Map();
+  for (const row of readShadowLog(days)) {
+    if (row.kind === 'reco') recos.push(row);
+    else if (row.kind === 'adopt' && row.session) {
+      if (!adoptBySession.has(row.session)) adoptBySession.set(row.session, new Set());
+      adoptBySession.get(row.session).add(lc(row.skill));
+    }
+  }
+  const grid = [];
+  for (const floor of floors) for (const margin of margins) {
+    let pass = 0, matchPass = 0, matchAdopt = 0;
+    for (const r of recos) {
+      if (replayGate(r, floor, margin) !== 'PASS') continue;
+      pass++;
+      if (r.session) { matchPass++; if (adoptBySession.get(r.session)?.has(lc(r.skill))) matchAdopt++; }
+    }
+    grid.push({ floor, margin, pass, matchPass, matchAdopt, precision: matchPass ? matchAdopt / matchPass : null });
+  }
+  return grid;
+}
+
+/**
+ * Phase-1 shadow orchestrator: retrieve → gate → log → cooldown on PASS.
+ * Emits NOTHING and writes NO live telemetry. `off` → no-op. Returns the verdict.
+ */
+export function recommendSkill(rdb, promptText, project, opts = {}) {
+  const mode = getRecommendMode();
+  if (mode === 'off') return { verdict: 'OFF', reason: 'off', candidate: null };
+  let candidates = [];
+  try { candidates = fetchInstalledSkillCandidates(rdb, promptText); } catch { /* ignore */ }
+  const cooldownSet = new Set(Object.keys(getRecoCooldown(project)));
+  const result = applyGate(candidates, promptText, cooldownSet);
+  // Eager replay vector (B3): applyGate short-circuits, so a row that BLOCKed at below_floor
+  // never evaluated intent/cooldown. Compute the gate's raw inputs unconditionally here so an
+  // offline sweep can recompute the verdict at any (floor, margin) without re-running retrieval.
+  const top = candidates[0] || null;
+  logShadowReco(project, {
+    // session id (B1): the cross-hook key that lets PostToolUse adoptions be paired with
+    // this reco in the SAME session — without it, precision is only a global name-set join.
+    session: opts.sessionId ?? null,
+    mode, verdict: result.verdict, reason: result.reason,
+    skill: top ? top.name : null,
+    relevance: top ? top.relevance : null,
+    rel2: candidates[1] ? candidates[1].relevance : null,
+    intentTop: top ? intentMatch(promptText, top) : false,
+    cooldownTop: top ? cooldownSet.has(String(top.name).toLowerCase()) : false,
+    ncand: candidates.length,
+    // #8259: UserPromptSubmit injection cite-recall was 25.8% until gated on explicit
+    // signal. Record signal-presence so the Phase-2 flip can test whether live injection
+    // should gate on it (the decisive lever per that lesson). Shadow does not gate on it.
+    hasSignal: opts.hasSignal ?? null,
+  });
+  // Simulate live cooldown timing so the shadow funnel reflects real injection cadence.
+  if (result.verdict === 'PASS') setRecoCooldown(project, result.candidate.name);
+  return result;
+}
+
+/** PostToolUse adoption probe — Skill is the only visible adoption signal (mem_use is pre-filtered). */
+export function recordSkillAdoption(toolName, toolInput, project, sessionId = null) {
+  if (getRecommendMode() === 'off') return;
+  if (toolName !== 'Skill') return;
+  const skill = toolInput && typeof toolInput === 'object' ? toolInput.skill : null;
+  if (!skill) return;
+  // session id (B1): same cross-hook key as the reco row, so adoptions pair to the
+  // would-be recommendation that fired earlier in this session (matched precision).
+  logShadowAdoption(project, { session: sessionId ?? null, skill: String(skill).toLowerCase() });
+}
+
+/** Human-readable funnel for `registry recommend-stats`. */
+export function formatFunnel(s) {
+  const blocks = Object.entries(s.blockByReason).sort((a, b) => b[1] - a[1])
+    .map(([k, v]) => `    ${k}: ${v}`).join('\n') || '    (none)';
+  const overlap = Object.keys(s.passSkills).filter(k => s.adoptSkills[k])
+    .map(k => `${k}(pass ${s.passSkills[k]}/adopt ${s.adoptSkills[k]})`).join(', ') || '(none)';
+  const passRate = s.reco ? (100 * s.pass / s.reco).toFixed(1) : '0.0';
+  const lines = [
+    'shadow recommendation funnel:',
+    `  reco=${s.reco}  pass=${s.pass} (${passRate}% of reco)  adopt=${s.adopt}`,
+    `  block reasons:\n${blocks}`,
+    `  PASS∩adopt (coarse precision proxy): ${overlap}`,
+  ];
+  // B2: session-paired matched precision + targeting lift (the flip-decision metrics).
+  if (typeof s.sessions === 'number') {
+    const mp = s.matched && s.matched.pass
+      ? `${s.matched.adopt}/${s.matched.pass} (${(100 * s.matched.precision).toFixed(0)}%)` : 'n/a';
+    const liftRows = Object.entries(s.lift || {}).filter(([, v]) => Number.isFinite(v.lift))
+      .sort((a, b) => b[1].lift - a[1].lift).slice(0, 5)
+      .map(([k, v]) => `${k}(lift ${v.lift.toFixed(2)}; ${v.hitSessions}/${v.passSessions} pass→adopt vs base ${(100 * v.baseRate).toFixed(0)}%)`)
+      .join(', ') || '(none)';
+    lines.push(`  sessions=${s.sessions}  matched precision (in-session PASS→adopt): ${mp}`);
+    lines.push(`  targeting lift (>1 = gate beats organic base rate): ${liftRows}`);
+  }
+  return lines.join('\n');
+}
+
+/** Human-readable threshold sweep for `registry recommend-stats --sweep`. */
+export function formatSweep(grid) {
+  const lines = ['gate threshold sweep (floor × margin → pass / matched precision):'];
+  for (const g of grid) {
+    const prec = Number.isFinite(g.precision) ? `${(100 * g.precision).toFixed(0)}%` : 'n/a';
+    lines.push(`  floor=${g.floor} margin=${g.margin}: pass=${g.pass}  matched=${g.matchAdopt}/${g.matchPass}  prec=${prec}`);
+  }
+  return lines.join('\n');
+}

package/registry-retriever.mjs

@@ -85,6 +85,23 @@ function extractCJKTokens(text) {
   return found;
 }
 
+/**
+ * English intent equivalents of any CJK_INTENT_MAP phrase present in `text` (deduped).
+ * Shared primitive so the skill-recommendation gate's intent match (registry-recommend.mjs)
+ * can bridge pure-中文 prompts to English intent_tags — Chinese has no word boundaries, so a
+ * phrase like "写测试" never token-matches the English tag "test" without this. Latin in keys
+ * ("修bug") is lowercased on the haystack so case can't miss; CJK is case-invariant.
+ */
+export function cjkIntentTokens(text) {
+  const s = String(text || '').toLowerCase();
+  const out = [];
+  const seen = new Set();
+  for (const [key, en] of Object.entries(CJK_INTENT_MAP)) {
+    if (s.includes(key) && !seen.has(en)) { seen.add(en); out.push(en); }
+  }
+  return out;
+}
+
 // ─── Query Building ──────────────────────────────────────────────────────────
 
 /**

package/scripts/user-prompt-search.js

@@ -11,6 +11,7 @@ import { writeFileSync, readFileSync, existsSync, renameSync } from 'fs';
 import { join, sep } from 'path';
 import Database from 'better-sqlite3';
 import { shouldSkip, computeEffectiveLen, detectIntent, shouldSkipByDedup, extractFiles, extractErrorSignature, DEDUP_STALE_MS, matchRegistrySkillName, detectMemOverride } from './prompt-search-utils.mjs';
+import { recommendSkill } from '../registry-recommend.mjs';
 
 // ─── Constants ──────────────────────────────────────────────────────────────
 
@@ -697,6 +698,25 @@ async function main() {
         }
       }
     } catch { /* silent — never block on registry failure */ }
+
+    // ─── L2: Intent-based skill recommendation (shadow-first, v3.12) ─────
+    // Distinct from L1 (explicit-name pointer): fires on intent even when the
+    // user did not name a skill. Phase 1 = shadow only (logs, never emits).
+    // Reuses a readonly registry DB; cooldown/shadow writes go to the FS.
+    try {
+      if (existsSync(REGISTRY_DB_PATH)) {
+        // #8259: explicit-signal presence is the decisive lever for UPS injection
+        // quality (UPS cite-recall was 25.8% until gated on it). Logged in shadow so
+        // Phase 2 can decide whether live injection gates on it. Shadow measures broadly.
+        const hasSignal = !!(extractErrorSignature(promptText) || extractFiles(promptText).length > 0 || detectIntent(promptText));
+        const rdb = new Database(REGISTRY_DB_PATH, { readonly: true });
+        rdb.pragma('busy_timeout = 500');
+        // CC session_id (hook stdin) is the cross-hook pairing key: PostToolUse adoptions
+        // in this same session join back to this reco for matched precision (B1).
+        try { recommendSkill(rdb, promptText, inferProject(), { hasSignal, sessionId: hookData.session_id }); }
+        finally { rdb.close(); }
+      }
+    } catch { /* silent — never block on recommendation failure */ }
   } catch {
     // Hooks must never break Claude Code — swallow all errors
   } finally {

package/secret-scrub.mjs

@@ -11,12 +11,14 @@ export const SECRET_PATTERNS = [
   // and short values (<6 chars) that are typically variable names not secrets.
   //
   // Split into two patterns so prose mentions don't get scrubbed:
-  //   1. Bare credential nouns (password|passwd|token|bearer) commonly appear in
-  //      English prose — "Marker token: xyzpdq", "the bearer: alice". We require
-  //      the keyword NOT to be preceded by an English-word + horizontal-space
-  //      (the prose mention shape). Code/config has the keyword at start-of-line,
-  //      after a separator, or in object-literal context — none of which match
-  //      "letter-then-space" preceding the keyword.
+  //   1. Bare credential nouns (password|passwd|token|bearer|secret) commonly appear
+  //      in English prose — "Marker token: xyzpdq", "the bearer: alice". The prose
+  //      mention shape is the `:` form, so the prose lookbehind (NOT preceded by
+  //      English-word + horizontal-space) guards ONLY the `:` separator. An `=` is
+  //      config-assignment syntax, never prose, so `<word> password=<secret>` ALWAYS
+  //      scrubs — without this split that leaked (the lookbehind skipped any noun
+  //      after "word ", regardless of separator). No pinned prose case uses `=` (all
+  //      are `:`), so the `=` arm is leak-closing with no FP shift on the protected set.
   //   2. Structured keys (api_key, auth_token, …) keep the original behavior —
   //      a separator/compound key is unambiguous config syntax even when
   //      preceded by prose ("see auth_token: shhhhhh").
@@ -26,7 +28,10 @@ export const SECRET_PATTERNS = [
   // keyword. Allowing a leading `_` catches those while the prose lookbehind still
   // excludes "Marker token: …". `secret` added so a bare SECRET=… with a mixed-alnum
   // value is covered (the hex-only assignment pattern below misses non-hex values).
-  [/((?<![A-Za-z][ \t])(?:\b|_)(?:password|passwd|token|bearer|secret)\s*[=:]\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
+  //   1a. `=` assignment → ALWAYS scrub (config syntax, never prose):
+  [/((?:\b|_)(?:password|passwd|token|bearer|secret)\s*=\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
+  //   1b. `:` separator → keep the prose lookbehind ("the token: alice" is prose):
+  [/((?<![A-Za-z][ \t])(?:\b|_)(?:password|passwd|token|bearer|secret)\s*:\s*)(?!process\.env\.)(?!new\s)(?!\w+\()(?!(?:null|undefined|true|false|None|nil|empty|""|''|0)\b)[^\s,;'"}\]]{6,}/gi, '$1***'],
   // access_token / refresh_token are the canonical OAuth2 field names — they were
   // missing from this KV list (drift vs the JSON list below). `(?:\b|_)` for the same
   // underscore-prefix reason.
@@ -47,8 +52,11 @@ export const SECRET_PATTERNS = [
   // object-literal / YAML / quoted-.env shapes. Split into the SAME two patterns as the
   // unquoted KV pairs above so prose survives — a quoted value does not turn prose into
   // config (`the token: "x"` is still prose, must NOT scrub; #8283 / utils.test.mjs:1090).
-  //   (a) bare credential nouns keep the prose lookbehind:
-  [/((?<![A-Za-z][ \t])(?:\b|_)(?:password|passwd|token|bearer|secret)\s*[=:]\s*)(['"])[^'"]{6,}\2/gi, '$1$2***$2'],
+  //   (a) bare credential nouns: `=` always scrubs; `:` keeps the prose lookbehind
+  //       (mirrors the unquoted 1a/1b split — a quoted value doesn't turn `:` prose
+  //       into config, but `<word> password="x"` is still a leak):
+  [/((?:\b|_)(?:password|passwd|token|bearer|secret)\s*=\s*)(['"])[^'"]{6,}\2/gi, '$1$2***$2'],
+  [/((?<![A-Za-z][ \t])(?:\b|_)(?:password|passwd|token|bearer|secret)\s*:\s*)(['"])[^'"]{6,}\2/gi, '$1$2***$2'],
   //   (b) structured keys + named env vars are unambiguous config even after a word
   //       (`see api_key: "x"` DOES scrub, mirroring the unquoted structured-key path):
   [/((?:\b|_)(?:pgpassword|pgpass|mysql_pwd|api[_-]?key|api[_-]?secret|secret[_-]?key|access[_-]?key|private[_-]?key|client[_-]?secret|auth[_-]?token|access[_-]?token|refresh[_-]?token)\s*[=:]\s*)(['"])[^'"]{6,}\2/gi, '$1$2***$2'],

package/server.mjs

@@ -997,7 +997,7 @@ server.registerTool(
         `Memory maintenance scan:`,
         `  Total active observations: ${stats.total}`,
         `  Near-duplicate pairs: ${duplicates.length}`,
-        `  Stale (>30d, imp=1, no access): ${stats.stale}`,
+        `  Stale (>30d, imp=1, no access, never injected): ${stats.stale}`,
         `  Broken (no title/narrative): ${stats.broken}`,
         `  Boostable (accessed>3, imp<3): ${stats.boostable}`,
         `  Pending purge (idle-marked): ${stats.pendingPurge}`,

package/source-files.mjs

@@ -15,6 +15,9 @@ export const SOURCE_FILES = [
   'package.json', 'package-lock.json', 'skill.md',
   'registry.mjs', 'registry-scanner.mjs', 'registry-indexer.mjs',
   'registry-retriever.mjs', 'resource-discovery.mjs',
+  // registry-recommend.mjs: statically imported by hook.mjs (PostToolUse adoption probe)
+  // and scripts/user-prompt-search.js (UserPromptSubmit shadow recommendation).
+  'registry-recommend.mjs',
   // registry-enricher/-github/-importer are dynamically imported by server.mjs
   // (mem_registry tool) and mem-cli.mjs (registry CLI subcommands). Missing
   // them from SOURCE_FILES silently broke those code paths prior to this fix.