claude-memory-layer 1.0.27 → 1.0.29

package/tests/core/retrieval-disclosure-service.test.ts

@@ -0,0 +1,264 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseDisclosureResultId,
+  parseDisclosureResultRef,
+  RetrievalDisclosureService
+} from '../../src/core/engine/retrieval-disclosure-service.js';
+import type { UnifiedRetrievalResult } from '../../src/core/retriever.js';
+import type { MemoryEvent, SharedTroubleshootingEntry } from '../../src/core/types.js';
+
+function event(id: string, content: string, timestamp: string, eventType: MemoryEvent['eventType'] = 'user_prompt'): MemoryEvent {
+  return {
+    id,
+    sessionId: 's1',
+    eventType,
+    content,
+    canonicalKey: `canonical/${id}`,
+    dedupeKey: `s1:${id}`,
+    timestamp: new Date(timestamp),
+    metadata: { filePath: `src/${id}.ts` }
+  };
+}
+
+const timeline = [
+  event('e1', 'Earlier user question about checkout memory', '2026-02-24T00:00:00.000Z'),
+  event('e2', 'Target assistant answer with checkout fix details', '2026-02-24T00:01:00.000Z', 'agent_response'),
+  event('e3', 'Later tool observation after applying the checkout fix', '2026-02-24T00:02:00.000Z', 'tool_observation')
+];
+
+const sharedEntry: SharedTroubleshootingEntry = {
+  entryId: 'shared-1',
+  sourceProjectHash: 'project-a',
+  sourceEntryId: 'e-shared',
+  title: 'Shared checkout troubleshooting',
+  symptoms: ['checkout fails'],
+  rootCause: 'stale cache',
+  solution: 'clear cache and retry',
+  topics: ['checkout'],
+  confidence: 0.88,
+  usageCount: 3,
+  promotedAt: new Date('2026-02-23T00:00:00.000Z'),
+  createdAt: new Date('2026-02-23T00:00:00.000Z')
+};
+
+function retrievalResult(sharedMemories: SharedTroubleshootingEntry[] = []): UnifiedRetrievalResult {
+  return {
+    memories: [{ event: timeline[1], score: 0.93, sessionContext: 'short surrounding context' }],
+    matchResult: {
+      match: { event: timeline[1], score: 0.93 },
+      confidence: 'high'
+    },
+    totalTokens: 42,
+    context: 'Target assistant answer with checkout fix details',
+    fallbackTrace: ['stage:primary:fast', 'fallback:deep'],
+    selectedDebug: [{ eventId: 'e2', score: 0.93, semanticScore: 0.82, lexicalScore: 0.41, recencyScore: 0.12 }],
+    candidateDebug: [{ eventId: 'e2', score: 0.93, semanticScore: 0.82, lexicalScore: 0.41, recencyScore: 0.12 }],
+    sharedMemories
+  };
+}
+
+function service(
+  result: UnifiedRetrievalResult = retrievalResult(),
+  overrides: {
+    initialize?: () => Promise<void>;
+    getEvent?: (id: string) => Promise<MemoryEvent | null>;
+    getSessionEvents?: (sessionId: string) => Promise<MemoryEvent[]>;
+    sharedStore?: { get(entryId: string): Promise<SharedTroubleshootingEntry | null> };
+  } = {}
+) {
+  return new RetrievalDisclosureService({
+    initialize: overrides.initialize ?? (async () => {}),
+    retrievalOrchestrator: {
+      retrieveMemories: async () => result
+    },
+    eventStore: {
+      getEvent: overrides.getEvent ?? (async (id: string) => timeline.find((item) => item.id === id) ?? null),
+      getSessionEvents: overrides.getSessionEvents ?? (async (sessionId: string) => timeline.filter((item) => item.sessionId === sessionId))
+    },
+    sharedStore: overrides.sharedStore
+  });
+}
+
+describe('RetrievalDisclosureService', () => {
+  it('keeps the legacy event-id parser while exposing a discriminated result-ref parser', () => {
+    expect(parseDisclosureResultId('event:e2')).toBe('e2');
+    expect(parseDisclosureResultId('e2')).toBe('e2');
+    expect(parseDisclosureResultId('shared:shared-1')).toBe('shared:shared-1');
+    expect(parseDisclosureResultRef('event:e2')).toEqual({ kind: 'event', eventId: 'e2' });
+    expect(parseDisclosureResultRef('shared:shared-1')).toEqual({ kind: 'shared', entryId: 'shared-1' });
+  });
+
+  it('search returns spec-aligned compact envelopes with reasons and source refs', async () => {
+    const out = await service().search('checkout fix', { topK: 1, sessionId: 's1' });
+
+    expect(out.meta).toMatchObject({
+      total: 1,
+      usedVector: true,
+      usedKeyword: true,
+      fallbackApplied: true
+    });
+    expect(out.results[0]).toMatchObject({
+      id: 'event:e2',
+      resultType: 'source',
+      score: 0.93,
+      snippet: 'Target assistant answer with checkout fix details',
+      sourceRef: 'event:e2',
+      sessionId: 's1',
+      metadata: {
+        eventId: 'e2',
+        eventType: 'agent_response',
+        canonicalKey: 'canonical/e2'
+      }
+    });
+    expect(out.results[0].reasons).toEqual(
+      expect.arrayContaining([
+        'semantic_match',
+        'keyword_match',
+        'recent_relevance',
+        'continuity_link'
+      ])
+    );
+  });
+
+  it('reports keyword-only fast retrieval without claiming vector usage', async () => {
+    const keywordOnly = {
+      ...retrievalResult(),
+      fallbackTrace: ['stage:primary:fast']
+    };
+
+    const out = await service(keywordOnly).search('checkout fix', { strategy: 'fast' });
+
+    expect(out.meta).toMatchObject({
+      usedVector: false,
+      usedKeyword: true,
+      fallbackApplied: false
+    });
+    expect(out.results[0].reasons).toContain('keyword_match');
+    expect(out.results[0].reasons).not.toContain('semantic_match');
+    expect(out.results[0].reasons).not.toContain('summary_fallback');
+  });
+
+  it('search includes shared memories instead of silently dropping them', async () => {
+    const out = await service(retrievalResult([sharedEntry])).search('checkout fix', { includeShared: true });
+
+    expect(out.meta.total).toBe(2);
+    expect(out.results.find((item) => item.id === 'shared:shared-1')).toMatchObject({
+      resultType: 'rule',
+      title: 'Shared checkout troubleshooting',
+      snippet: 'clear cache and retry',
+      sourceRef: 'shared:shared-1',
+      reasons: ['semantic_match'],
+      metadata: {
+        sourceProjectHash: 'project-a',
+        sourceEntryId: 'e-shared'
+      }
+    });
+  });
+
+  it('expand returns target envelope, surrounding context, and related source references', async () => {
+    const expanded = await service().expand('event:e2', { windowSize: 1 });
+
+    expect(expanded?.target.id).toBe('event:e2');
+    expect(expanded?.target.snippet).toContain('checkout fix details');
+    expect(expanded?.surroundingFacts?.map((item) => item.id)).toEqual(['event:e1', 'event:e3']);
+    expect(expanded?.relatedSources?.[0]).toMatchObject({
+      sourceRef: 'event:e1',
+      sourceType: 'raw_event',
+      eventIds: ['e1']
+    });
+    expect(expanded?.expandedContext).toContain('[agent_response] Target assistant answer');
+  });
+
+  it('source returns a spec-aligned source reference plus raw drill-down events', async () => {
+    const source = await service().source('event:e2');
+
+    expect(source).toMatchObject({
+      sourceRef: 'event:e2',
+      sourceType: 'raw_event',
+      eventIds: ['e2']
+    });
+    expect(source?.rawEvents[0].id).toBe('e2');
+    expect(source?.rawEvents[0].metadata).toEqual({ filePath: 'src/e2.ts' });
+  });
+
+  it('expand and source keep event drill-down lightweight without full retrieval initialization', async () => {
+    let initializeCalls = 0;
+    const disclosure = service(retrievalResult(), {
+      initialize: async () => {
+        initializeCalls += 1;
+        throw new Error('full initialization should not be called for drill-down reads');
+      }
+    });
+
+    await expect(disclosure.expand('event:e2')).resolves.toMatchObject({
+      target: { id: 'event:e2' }
+    });
+    await expect(disclosure.source('event:e2')).resolves.toMatchObject({
+      sourceRef: 'event:e2'
+    });
+    expect(initializeCalls).toBe(0);
+  });
+
+  it('expands shared disclosure results through the shared store without fake local events', async () => {
+    const lookedUpEventIds: string[] = [];
+    const expanded = await service(retrievalResult([sharedEntry]), {
+      getEvent: async (id: string) => {
+        lookedUpEventIds.push(id);
+        return timeline.find((item) => item.id === id) ?? null;
+      },
+      sharedStore: { get: async (entryId: string) => entryId === sharedEntry.entryId ? sharedEntry : null }
+    }).expand('shared:shared-1');
+
+    expect(expanded?.target).toMatchObject({
+      id: 'shared:shared-1',
+      resultType: 'rule',
+      title: 'Shared checkout troubleshooting',
+      metadata: {
+        sourceProjectHash: 'project-a',
+        sourceEntryId: 'e-shared'
+      }
+    });
+    expect(expanded?.relatedSources).toEqual([
+      {
+        sourceRef: 'shared:shared-1',
+        sourceType: 'shared_troubleshooting',
+        eventIds: [],
+        metadata: {
+          sourceProjectHash: 'project-a',
+          sourceEntryId: 'e-shared',
+          topics: ['checkout']
+        }
+      }
+    ]);
+    expect(expanded?.expandedContext).toContain('Root cause: stale cache');
+    expect(lookedUpEventIds).toEqual([]);
+  });
+
+  it('resolves shared disclosure sources without pretending they are local raw events', async () => {
+    const source = await service(retrievalResult([sharedEntry]), {
+      sharedStore: { get: async (entryId: string) => entryId === sharedEntry.entryId ? sharedEntry : null }
+    }).source('shared:shared-1');
+
+    expect(source).toMatchObject({
+      sourceRef: 'shared:shared-1',
+      sourceType: 'shared_troubleshooting',
+      eventIds: [],
+      rawEvents: [],
+      metadata: {
+        sourceProjectHash: 'project-a',
+        sourceEntryId: 'e-shared',
+        topics: ['checkout'],
+        rootCause: 'stale cache',
+        solution: 'clear cache and retry'
+      }
+    });
+    expect(source?.primaryEvent).toBeUndefined();
+  });
+
+  it('returns null when expand/source cannot resolve the result id', async () => {
+    await expect(service().expand('event:missing')).resolves.toBeNull();
+    await expect(service().source('event:missing')).resolves.toBeNull();
+    await expect(service().expand('shared:missing')).resolves.toBeNull();
+    await expect(service().source('shared:missing')).resolves.toBeNull();
+  });
+});

package/tests/core/retrieval-orchestrator.test.ts

@@ -0,0 +1,403 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { RetrievalOrchestrator, type RetrievalAccessStore } from '../../src/core/engine/retrieval-orchestrator.js';
+import type { Retriever, UnifiedRetrievalResult } from '../../src/core/retriever.js';
+import type { MemoryEvent } from '../../src/core/types.js';
+
+function event(id: string): MemoryEvent {
+  return {
+    id,
+    sessionId: 's1',
+    eventType: 'user_prompt',
+    content: 'remembered project context',
+    canonicalKey: `test/${id}`,
+    dedupeKey: `s1:${id}`,
+    timestamp: new Date('2026-02-24T00:00:00.000Z'),
+    metadata: {}
+  };
+}
+
+function retrievalResult(id = 'e1'): UnifiedRetrievalResult {
+  const memoryEvent = event(id);
+  return {
+    memories: [{ event: memoryEvent, score: 0.91 }],
+    matchResult: {
+      match: { event: memoryEvent, score: 0.91 },
+      confidence: 'high'
+    },
+    totalTokens: 12,
+    context: 'remembered project context',
+    fallbackTrace: ['stage:primary:fast'],
+    selectedDebug: [{ eventId: id, score: 0.91, semanticScore: 0.8, lexicalScore: 0.2, recencyScore: 0.1 }],
+    candidateDebug: [{ eventId: id, score: 0.91, semanticScore: 0.8, lexicalScore: 0.2, recencyScore: 0.1 }]
+  };
+}
+
+function stats() {
+  return {
+    avgScore: 0.8,
+    totalEvaluated: 30,
+    totalRetrievals: 40,
+    helpful: 20,
+    neutral: 5,
+    unhelpful: 5
+  };
+}
+
+function noopAccessStore(): RetrievalAccessStore {
+  return {
+    incrementAccessCount: async (_eventIds) => {},
+    recordRetrieval: async (_eventId, _sessionId, _score, _query) => {}
+  };
+}
+
+afterEach(() => {
+  delete process.env.MEMORY_RERANK_WEIGHT_SEMANTIC;
+  delete process.env.MEMORY_RERANK_WEIGHT_LEXICAL;
+  delete process.env.MEMORY_RERANK_WEIGHT_RECENCY;
+});
+
+describe('RetrievalOrchestrator', () => {
+  it('delegates project retrieval with strict project scope and records a trace', async () => {
+    let initialized = 0;
+    let retrieveArgs: { query: string; options: Record<string, unknown> } | null = null;
+    const traces: Array<Record<string, unknown>> = [];
+
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieve(query: string, options: Record<string, unknown>) {
+        retrieveArgs = { query, options };
+        return retrievalResult('e1');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async (input) => { traces.push(input); }
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-1',
+      hasSharedStore: () => false
+    });
+
+    const out = await orchestrator.retrieveMemories('project query', { topK: 3, sessionId: 's1' });
+
+    expect(out.memories[0]?.event.id).toBe('e1');
+    expect(initialized).toBe(1);
+    expect(retrieveArgs?.query).toBe('project query');
+    expect(retrieveArgs?.options.projectHash).toBe('project-1');
+    expect(retrieveArgs?.options.projectScopeMode).toBe('strict');
+    expect(traces[0]).toMatchObject({
+      sessionId: 's1',
+      projectHash: 'project-1',
+      queryText: 'project query',
+      strategy: 'auto',
+      candidateEventIds: ['e1'],
+      selectedEventIds: ['e1'],
+      confidence: 'high',
+      fallbackTrace: ['stage:primary:fast']
+    });
+  });
+
+  it('can skip automatic trace recording for read-only retrieval callers', async () => {
+    const traces: Array<Record<string, unknown>> = [];
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieve() {
+        return retrievalResult('readonly-e1');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => {},
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async (input) => { traces.push(input); }
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-readonly',
+      hasSharedStore: () => false
+    });
+
+    await orchestrator.retrieveMemories('secret-bearing read-only query', {
+      topK: 3,
+      recordTrace: false
+    });
+
+    expect(traces).toEqual([]);
+  });
+
+  it('does not run full runtime initialization for local fast retrieval', async () => {
+    let initialized = 0;
+    let statsReads = 0;
+    let retrieveArgs: { query: string; options: Record<string, unknown> } | null = null;
+    const traces: Array<Record<string, unknown>> = [];
+
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieve(query: string, options: Record<string, unknown>) {
+        retrieveArgs = { query, options };
+        return retrievalResult('fast-e1');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => { statsReads += 1; return stats(); },
+        recordRetrievalTrace: async (input) => { traces.push(input); }
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-fast',
+      hasSharedStore: () => false
+    });
+
+    await orchestrator.retrieveMemories('fast keyword query', {
+      strategy: 'fast',
+      topK: 3,
+      minScore: 0.2
+    });
+
+    expect(initialized).toBe(0);
+    expect(statsReads).toBe(0);
+    expect(retrieveArgs?.options.strategy).toBe('fast');
+    expect(retrieveArgs?.options.projectHash).toBe('project-fast');
+    expect(traces[0]).toMatchObject({
+      strategy: 'fast',
+      candidateEventIds: ['fast-e1'],
+      selectedEventIds: ['fast-e1']
+    });
+  });
+
+  it('keeps fast retrieval lightweight when shared search is requested but unavailable', async () => {
+    let initialized = 0;
+    let localRetrieveCalls = 0;
+    let unifiedRetrieveCalls = 0;
+
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieve(_query: string, options: Record<string, unknown>) {
+        localRetrieveCalls += 1;
+        expect(options.includeShared).toBe(true);
+        expect(options.strategy).toBe('fast');
+        return retrievalResult('local-fast-shared-request');
+      },
+      async retrieveUnified() {
+        unifiedRetrieveCalls += 1;
+        return retrievalResult('unexpected-unified');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-fast',
+      hasSharedStore: () => false
+    });
+
+    const out = await orchestrator.retrieveMemories('fast query without shared store', {
+      strategy: 'fast',
+      includeShared: true,
+      topK: 3
+    });
+
+    expect(out.memories[0]?.event.id).toBe('local-fast-shared-request');
+    expect(initialized).toBe(0);
+    expect(localRetrieveCalls).toBe(1);
+    expect(unifiedRetrieveCalls).toBe(0);
+  });
+
+  it('initializes the full runtime for fast retrieval when an actual shared store is available', async () => {
+    let initialized = 0;
+    let retrieveUnifiedArgs: { query: string; options: Record<string, unknown> } | null = null;
+
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieveUnified(query: string, options: Record<string, unknown>) {
+        retrieveUnifiedArgs = { query, options };
+        return retrievalResult('shared-fast');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-fast',
+      hasSharedStore: () => true
+    });
+
+    await orchestrator.retrieveMemories('fast shared query', {
+      strategy: 'fast',
+      includeShared: true,
+      topK: 3
+    });
+
+    expect(initialized).toBe(1);
+    expect(retrieveUnifiedArgs?.query).toBe('fast shared query');
+    expect(retrieveUnifiedArgs?.options.includeShared).toBe(true);
+  });
+
+  it('uses unified retrieval and normalized configured rerank weights when shared search is enabled', async () => {
+    process.env.MEMORY_RERANK_WEIGHT_SEMANTIC = '3';
+    process.env.MEMORY_RERANK_WEIGHT_LEXICAL = '1';
+    process.env.MEMORY_RERANK_WEIGHT_RECENCY = '1';
+
+    let retrieveUnifiedArgs: { query: string; options: Record<string, unknown> } | null = null;
+
+    const fakeRetriever = {
+      setQueryRewriter() {},
+      async retrieveUnified(query: string, options: Record<string, unknown>) {
+        retrieveUnifiedArgs = { query, options };
+        return retrievalResult('shared-e1');
+      }
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => {},
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => 'project-2',
+      hasSharedStore: () => true
+    });
+
+    await orchestrator.retrieveMemories('shared query', {
+      includeShared: true,
+      intentRewrite: true,
+      adaptiveRerank: true
+    });
+
+    expect(retrieveUnifiedArgs?.query).toBe('shared query');
+    expect(retrieveUnifiedArgs?.options.includeShared).toBe(true);
+    expect(retrieveUnifiedArgs?.options.intentRewrite).toBe(true);
+    expect(retrieveUnifiedArgs?.options.rerankWeights).toEqual({
+      semantic: 0.6,
+      lexical: 0.2,
+      recency: 0.2
+    });
+  });
+
+  it('formats high-confidence context through the orchestrator facade', () => {
+    const fakeRetriever = {
+      setQueryRewriter() {}
+    } as unknown as Retriever;
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => {},
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: noopAccessStore(),
+      getProjectHash: () => null,
+      hasSharedStore: () => false
+    });
+
+    expect(orchestrator.formatAsContext(retrievalResult())).toContain('High-confidence memory match');
+  });
+
+  it('records prompt memory access through the orchestrator access port without full initialization', async () => {
+    let initialized = 0;
+    const accessCalls: string[][] = [];
+    const fakeRetriever = {
+      setQueryRewriter() {}
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: {
+        incrementAccessCount: async (eventIds) => { accessCalls.push(eventIds); },
+        recordRetrieval: async () => {}
+      },
+      getProjectHash: () => null,
+      hasSharedStore: () => false
+    });
+
+    await orchestrator.incrementMemoryAccess(['e1', 'e2']);
+
+    expect(initialized).toBe(0);
+    expect(accessCalls).toEqual([['e1', 'e2']]);
+  });
+
+  it('skips prompt memory access tracking for empty event id lists', async () => {
+    let initialized = 0;
+    let accessCalls = 0;
+    const fakeRetriever = {
+      setQueryRewriter() {}
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: {
+        incrementAccessCount: async () => { accessCalls += 1; },
+        recordRetrieval: async () => {}
+      },
+      getProjectHash: () => null,
+      hasSharedStore: () => false
+    });
+
+    await orchestrator.incrementMemoryAccess([]);
+
+    expect(initialized).toBe(0);
+    expect(accessCalls).toBe(0);
+  });
+
+  it('records retrieval helpfulness events through the orchestrator access port', async () => {
+    let initialized = 0;
+    const retrievalCalls: Array<{ eventId: string; sessionId: string; score: number; query: string }> = [];
+    const fakeRetriever = {
+      setQueryRewriter() {}
+    } as unknown as Retriever;
+
+    const orchestrator = new RetrievalOrchestrator({
+      initialize: async () => { initialized += 1; },
+      retriever: fakeRetriever,
+      traceStore: {
+        getHelpfulnessStats: async () => stats(),
+        recordRetrievalTrace: async () => {}
+      },
+      accessStore: {
+        incrementAccessCount: async () => {},
+        recordRetrieval: async (eventId, sessionId, score, query) => {
+          retrievalCalls.push({ eventId, sessionId, score, query });
+        }
+      },
+      getProjectHash: () => 'project-1',
+      hasSharedStore: () => false
+    });
+
+    await orchestrator.recordRetrieval('e1', 's1', 0.82, 'thin core');
+
+    expect(initialized).toBe(1);
+    expect(retrievalCalls).toEqual([
+      { eventId: 'e1', sessionId: 's1', score: 0.82, query: 'thin core' }
+    ]);
+  });
+});

package/tests/core/retrieval-quality.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+import {
+  isGenericContinuationQuery,
+  isLowSignalContextContent
+} from '../../src/core/retrieval-quality.js';
+
+describe('retrieval quality guards', () => {
+  it('recognizes short generic continuation prompts', () => {
+    expect(isGenericContinuationQuery('continue')).toBe(true);
+    expect(isGenericContinuationQuery('what next?')).toBe(true);
+    expect(isGenericContinuationQuery('다음 추천작업은 뭐야?')).toBe(true);
+    expect(isGenericContinuationQuery('이어서 진행해줘')).toBe(true);
+  });
+
+  it('does not classify topic-specific next/recommendation/debug prompts as generic', () => {
+    expect(isGenericContinuationQuery('next task for search UI')).toBe(false);
+    expect(isGenericContinuationQuery('recommendation for auth design')).toBe(false);
+    expect(isGenericContinuationQuery('이 오류 뭐야?')).toBe(false);
+    expect(isGenericContinuationQuery('다음 작업은 retrieval-quality.ts에서 뭐야?')).toBe(false);
+  });
+
+  it('detects low-signal context artifacts', () => {
+    expect(isLowSignalContextContent('<environment_context><cwd>/repo/app</cwd></environment_context>')).toBe(true);
+    expect(isLowSignalContextContent('prefix <environment_context><cwd>/repo/app</cwd></environment_context> suffix')).toBe(true);
+    expect(isLowSignalContextContent('<command-name>/model</command-name>\n<local-command-stdout>opus</local-command-stdout>')).toBe(true);
+    expect(isLowSignalContextContent('# AGENTS.md instructions for /repo/app <INSTRUCTIONS> ## Skills A skill is local instructions.')).toBe(true);
+    expect(isLowSignalContextContent('Understood, stopping here. Let me know when you would like to continue with the design doc review.')).toBe(true);
+    expect(isLowSignalContextContent('Implementation note: suppress the stale phrase "Understood, stopping here. Let me know when you would like to continue." from context packs.')).toBe(false);
+    expect(isLowSignalContextContent('Merged PR #15 and synced local main.')).toBe(false);
+  });
+});