@cachly-dev/mcp-server 0.10.117 → 0.10.119

package/dist/src/handlers/brain.js

@@ -2,13 +2,20 @@ import { execSync } from 'node:child_process';
 import { calculateConfidence, confidenceBadge, STRUCTURED_TEMPLATES, CONFIDENCE_WARN_VALUE, CONFIDENCE_STALE_VALUE, CONFIDENCE_WARN_DAYS } from '../confidence.js';
 import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge, ckgUpsertPersonNode, ckgUpsertFileNode, ckgRecordCollaboration, ckgUpsertServiceNode } from '../ckg.js';
 import { safeJsonParse, scanKeys } from '../utils.js';
-import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope } from './team.js';
+import { getRole, ROLE_BADGE, getScopes, lessonVisibleToScope, reviewModeEnabled, storeLessonProposal } from './team.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.115';
+const MCP_VERSION = '0.10.119';
 const WHATS_NEW = {
+    '0.10.119': [
+        `🔍 **Explainable briefings — provenance in every warning**`,
+        `  📎 \`/briefing\` warnings now carry \`outcome\`, \`author\`, \`learned_at\` and \`matched_on\` (the context tokens that triggered the warning) — editors can show WHY a fix hint fired, not just what it claims.`,
+        `  🧰 VS Code 0.12.0 uses this: severity + confidence in the toast, full lesson card with provenance, "Not helpful" per-file suppression, reviewable CLS auto-learns.`,
+        `  🧹 CI docs now describe exactly what ships: scan mode uses the REST \`/scan\` endpoint, the GitLab template covers learn/scan/confirm.`,
+        `  📊 126 MCP tools`,
+    ],
     '0.10.115': [
         `🔧 **\`brain_get_pref\` + \`brain_set_pref\` — persistent Brain preferences**`,
         `  📖 \`brain_get_pref\` reads back any stored preference (omit key to list all).`,
@@ -402,6 +409,21 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], depends_on = [], author = '', visibility = 'team', service = '', service_kind = 'service', group = '', } = args;
             const redis = await getConnection(instance_id);
             const ts = new Date().toISOString();
+            // ── Lessons-Review workflow (P1-1) ─────────────────────────────────────
+            // When the org enabled pending-mode on this (shared) brain, team-visible
+            // lessons become proposals awaiting owner/admin approval instead of
+            // landing in the recall keyspace. Private notes stay direct — they never
+            // surface in team recall anyway. Flag absent = direct write, as before.
+            if (visibility !== 'private' && await reviewModeEnabled(redis, instance_id)) {
+                return storeLessonProposal(redis, topic, {
+                    topic, outcome, what_worked, what_failed, context: ctx, severity,
+                    file_paths, commands, tags, depends_on,
+                    ...(author ? { author } : {}),
+                    ...(service ? { service } : {}),
+                    ...(group ? { group: String(group).toLowerCase().trim() } : {}),
+                    visibility, recall_count: 0, ts, confidence: 1.0, version: 3,
+                });
+            }
             // ── Structured template hints ──────────────────────────────────────────
             const category = topic.split(':')[0];
             const template = STRUCTURED_TEMPLATES[category];
@@ -416,12 +438,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // ── Deduplication + audit trail ────────────────────────────────────────
             let isUpdate = false;
             let recallCount = 0;
+            let lastRecalledAt;
             let auditTrail = [];
             const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
             if (existingRaw) {
                 try {
                     const prev = JSON.parse(existingRaw);
                     recallCount = prev.recall_count ?? 0;
+                    lastRecalledAt = prev.last_recalled_at; // learn never stamps it — only recall does
                     auditTrail = prev.audit_trail ?? [];
                     auditTrail.push({ ts, action: 'updated', prev_outcome: prev.outcome });
                     if (auditTrail.length > 20)
@@ -521,6 +545,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 ...(group ? { group: String(group).toLowerCase().trim() } : {}),
                 visibility,
                 recall_count: recallCount,
+                ...(lastRecalledAt ? { last_recalled_at: lastRecalledAt } : {}),
                 ts,
                 verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
                 confidence: 1.0,
@@ -788,11 +813,14 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const ref = lesson.verified_at ?? lesson.ts;
                 const ageDays = (Date.now() - new Date(ref).getTime()) / 86400000;
                 const badge = confidenceBadge(confidence, ageDays);
-                // Recall resets verified_at (confidence clock restart)
+                // Recall resets verified_at (confidence clock restart) and stamps
+                // last_recalled_at so the recall-quality dashboard can measure recency.
+                const recalledAt = new Date().toISOString();
                 const updatedLesson = {
                     ...lesson,
                     recall_count: (lesson.recall_count ?? 0) + 1,
-                    verified_at: new Date().toISOString(),
+                    verified_at: recalledAt,
+                    last_recalled_at: recalledAt,
                     confidence: 1.0,
                 };
                 await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
@@ -837,7 +865,9 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     trustBadge,
                     `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
                     ``,
-                    `**What worked:** ${lesson.what_worked}`,
+                    // what_worked may be empty for unresolved failure lessons (the API
+                    // accepts empty what_worked when outcome=failure) — skip the line.
+                    lesson.what_worked ? `**What worked:** ${lesson.what_worked}` : '',
                     lesson.what_failed ? `**What failed (avoid this):** ${lesson.what_failed}` : '',
                     lesson.context ? `**Context:** ${lesson.context}` : '',
                     (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f) => `\`${f}\``).join(', ')}` : '',
@@ -906,6 +936,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             // Exclude archived lessons — they are kept for audit but must not surface in recall.
             const lessonMatches = kwMatches.filter(m => m.key.startsWith('cachly:lesson:best:'));
             let crossAuthorThisCall = 0;
+            let successRecallsThisCall = 0;
             for (const m of lessonMatches.slice(0, 5)) {
                 const existing = await redis.get(m.key).catch(() => null);
                 if (existing) {
@@ -914,7 +945,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     if (lesson?.state === 'archived')
                         continue;
                     if (lesson) {
-                        const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: new Date().toISOString() };
+                        const recalledAt = new Date().toISOString();
+                        const updated = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1, verified_at: recalledAt, last_recalled_at: recalledAt };
                         redis.set(m.key, JSON.stringify(updated)).catch(() => { });
                         const sev = lesson.severity;
                         const savedMins = sev === 'critical' ? 240 : sev === 'major' ? 60 : 30;
@@ -934,6 +966,8 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                             ckgUpdateEdge(redis, reqPersonId, 'collaborates', authPersonId, true).catch(() => { });
                             ckgUpdateEdge(redis, authPersonId, 'collaborates', reqPersonId, true).catch(() => { });
                         }
+                        if (lesson.outcome === 'success')
+                            successRecallsThisCall++;
                         // Surface banner for proven successes (recall_count >= 1 means it's been validated)
                         if (lesson.outcome === 'success' && (lesson.recall_count ?? 0) >= 1) {
                             savedHere.push({
@@ -949,8 +983,11 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 }
             }
             // Metric 1 (time-to-first-recall): stamp the first time recall returned a
-            // proven lesson. SET NX so only the first successful recall wins.
-            if (savedHere.length > 0) {
+            // successful lesson. SET NX so only the first successful recall wins.
+            // Deliberately NOT gated on savedHere: savedHere requires a pre-existing
+            // recall_count >= 1, which would delay the stamp until the SECOND recall
+            // and inflate every TTFR percentile derived from it.
+            if (successRecallsThisCall > 0) {
                 redis.set(`cachly:stats:first_recall_at:${instance_id}`, new Date().toISOString(), 'EX', 365 * 86400, 'NX').catch(() => { });
             }
             // ── Layer 2: Semantic search (parallel, optional) ────────────────────────