byterover-cli 3.0.1 → 3.2.0

package/dist/agent/infra/tools/implementations/search-knowledge-service.js

@@ -1,21 +1,23 @@
 import MiniSearch from 'minisearch';
+import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { removeStopwords } from 'stopword';
-import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, SUMMARY_INDEX_FILE } from '../../../../server/constants.js';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, OVERVIEW_EXTENSION, SHARED_SOURCE_LOCAL_SCORE_BOOST, SUMMARY_INDEX_FILE, } from '../../../../server/constants.js';
 import { parseFrontmatterScoring, updateScoringInContent, } from '../../../../server/core/domain/knowledge/markdown-writer.js';
 import { applyDecay, applyDefaultScoring, compoundScore, determineTier, recordAccessHits, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
+import { loadSources } from '../../../../server/core/domain/source/source-schema.js';
 import { isArchiveStub, isDerivedArtifact } from '../../../../server/infra/context-tree/derived-artifact.js';
-import { parseArchiveStubFrontmatter, parseSummaryFrontmatter } from '../../../../server/infra/context-tree/summary-frontmatter.js';
+import { parseArchiveStubFrontmatter, parseSummaryFrontmatter, } from '../../../../server/infra/context-tree/summary-frontmatter.js';
 import { isPathLikeQuery, matchMemoryPath, parseSymbolicQuery } from './memory-path-matcher.js';
 import { buildReferenceIndex, buildSymbolTree, getSubtreeDocumentIds, getSymbolKindLabel, getSymbolOverview, MemorySymbolKind, } from './memory-symbol-tree.js';
 const MAX_CONTEXT_TREE_FILES = 10_000;
 const DEFAULT_CACHE_TTL_MS = 5000;
 /** Bump when MINISEARCH_OPTIONS fields/boost change to invalidate cached indexes */
-const INDEX_SCHEMA_VERSION = 4;
+const INDEX_SCHEMA_VERSION = 5;
 /** Only include results whose normalized score is at least this fraction of the top result's score */
-const SCORE_GAP_RATIO = 0.75;
+const SCORE_GAP_RATIO = 0.7;
 /** Minimum normalized score for the top result. Below this, the query is considered out-of-domain */
-const MINIMUM_RELEVANCE_SCORE = 0.6;
+const MINIMUM_RELEVANCE_SCORE = 0.45;
 /** Normalized score threshold above which results are trusted despite unmatched query terms */
 const UNMATCHED_TERM_SCORE_THRESHOLD = 0.85;
 /** Minimum query term length to consider "significant" for OOD term-based detection */
@@ -33,6 +35,66 @@ const CHUNK_OVERLAP_CHARS = 120;
 function normalizeScore(rawScore) {
     return rawScore / (1 + rawScore);
 }
+function getSymbolPath(origin, relativePath) {
+    if (origin.origin === 'local') {
+        return relativePath;
+    }
+    return `[${origin.alias ?? origin.originKey}]:${relativePath}`;
+}
+/**
+ * Propagate BM25 scores upward to parent domain/topic nodes.
+ *
+ * For each matched result, walks the parent chain and computes a decayed boost
+ * (score * propagationFactor per level). New summary entries are added for
+ * parent nodes that have a _index.md in summaryMap but are not already in results.
+ *
+ * @param results - Already-enriched search results (gap-ratio filtered)
+ * @param symbolTree - Symbol tree for parent-chain traversal
+ * @param summaryMap - Map of _index.md file paths → SummaryDocLike (for excerpt/metadata)
+ * @param symbolPathDocMap - symbolPath → IndexedDocument lookup for context.md fallback
+ * @param propagationFactor - Score multiplier per level up (default 0.55)
+ * @returns New parent entries only — caller merges and re-sorts
+ */
+function propagateScoresToParents(results, symbolTree, summaryMap, symbolPathDocMap, propagationFactor = 0.55) {
+    const boosts = new Map();
+    for (const r of results) {
+        const symbol = symbolTree.symbolMap.get(r.path);
+        let parent = symbol?.parent;
+        let factor = propagationFactor;
+        while (parent) {
+            const cur = boosts.get(parent.path) ?? 0;
+            boosts.set(parent.path, Math.max(cur, r.bm25Score * factor));
+            parent = parent.parent;
+            factor *= propagationFactor;
+        }
+    }
+    const existingPaths = new Set(results.map((r) => r.path));
+    const boosted = [];
+    for (const [parentPath, score] of boosts.entries()) {
+        if (existingPaths.has(parentPath))
+            continue;
+        const doc = getSummarySource(parentPath, summaryMap, symbolPathDocMap);
+        if (!doc)
+            continue;
+        // Propagate the strongest child BM25 signal upward, then apply the parent
+        // summary's own scoring exactly once. This avoids double-counting lifecycle
+        // weights that are already baked into child compound scores.
+        const finalScore = doc.scoring
+            ? compoundScore(score, doc.scoring.importance ?? 50, doc.scoring.recency ?? 0.5, doc.scoring.maturity ?? 'draft')
+            : score;
+        boosted.push({
+            backlinkCount: 0,
+            excerpt: doc.excerpt,
+            path: parentPath,
+            score: finalScore,
+            symbolKind: 'summary',
+            title: parentPath,
+        });
+    }
+    return boosted;
+}
+/** Numeric rank for maturity tiers — used for minMaturity filtering in both BM25 and propagated results. */
+const MATURITY_TIER_RANK = { core: 3, draft: 1, validated: 2 };
 const MINISEARCH_OPTIONS = {
     fields: ['title', 'content', 'path'],
     idField: 'id',
@@ -43,6 +105,30 @@ const MINISEARCH_OPTIONS = {
     },
     storeFields: ['title', 'path'],
 };
+function getSummaryAccessPath(path, summaryMap, symbolPathDocMap) {
+    return getSummarySource(path, summaryMap, symbolPathDocMap)?.path ?? `${path}/${SUMMARY_INDEX_FILE}`;
+}
+function getSummarySource(path, summaryMap, symbolPathDocMap) {
+    const summaryDoc = summaryMap.get(`${path}/${SUMMARY_INDEX_FILE}`);
+    if (summaryDoc) {
+        return {
+            excerpt: summaryDoc.excerpt ?? '',
+            path: summaryDoc.path,
+            scoring: summaryDoc.scoring,
+        };
+    }
+    // Look up context.md via symbolPath-keyed map since documentMap keys are
+    // origin-qualified (e.g. 'local::path') but callers use symbol tree paths.
+    const contextDoc = symbolPathDocMap.get(`${path}/context.md`);
+    if (contextDoc) {
+        return {
+            excerpt: extractExcerpt(contextDoc.content, contextDoc.title),
+            path: contextDoc.path,
+            scoring: contextDoc.scoring,
+        };
+    }
+    return undefined;
+}
 function filterStopWords(query) {
     const words = query.toLowerCase().split(/\s+/);
     const filtered = removeStopwords(words);
@@ -162,6 +248,9 @@ function extractExcerpt(content, query, maxLength = 800) {
     }
     return excerpt || cleanContent.slice(0, maxLength) + (cleanContent.length > maxLength ? '...' : '');
 }
+function stripMarkdownFrontmatter(content) {
+    return content.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, '').trim();
+}
 async function findMarkdownFilesWithMtime(fileSystem, contextTreePath) {
     try {
         const globResult = await fileSystem.globFiles(`**/*${CONTEXT_FILE_EXTENSION}`, {
@@ -197,67 +286,82 @@ function isCacheValid(cache, currentFiles) {
     }
     return true;
 }
-async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
-    const now = Date.now();
-    if (filesWithMtime.length === 0) {
-        const index = new MiniSearch(MINISEARCH_OPTIONS);
-        return {
-            contextTreePath,
-            documentMap: new Map(),
-            fileMtimes: new Map(),
-            index,
-            lastValidatedAt: now,
-            referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
-            schemaVersion: INDEX_SCHEMA_VERSION,
-            summaryMap: new Map(),
-            symbolTree: { root: [], symbolMap: new Map() },
-        };
-    }
-    // Partition files: _index.md → summaryFiles, derived artifacts → skip, rest → indexable
+/**
+ * Read and index documents from a single context tree origin.
+ * Returns documents with origin-qualified IDs (<originKey>::<path>)
+ * and summary docs keyed by origin-qualified paths.
+ */
+async function indexOriginDocuments(fileSystem, origin, filesWithMtime) {
+    // Partition files: _index.md → summaryFiles, .overview.md → overviewFiles (for cache
+    // invalidation + sibling detection), other derived artifacts → skip, rest → indexable
     const summaryFiles = [];
+    const overviewFiles = [];
     const indexableFiles = [];
+    // Track all known paths for sibling detection (e.g. .overview.md presence check)
+    const knownPaths = new Set(filesWithMtime.map((f) => f.path));
     for (const file of filesWithMtime) {
         const fileName = file.path.split('/').at(-1) ?? '';
         if (fileName === SUMMARY_INDEX_FILE) {
             summaryFiles.push(file);
         }
+        else if (file.path.endsWith(OVERVIEW_EXTENSION)) {
+            // Track mtimes so cache invalidates when a new .overview.md appears; not BM25-indexed
+            overviewFiles.push(file);
+        }
         else if (!isDerivedArtifact(file.path)) {
-            // Includes regular .md files AND .stub.md files (stubs are searchable)
             indexableFiles.push(file);
         }
-        // .full.md and _manifest.json are skipped (isDerivedArtifact returns true)
+        // .full.md, .abstract.md, and _manifest.json are skipped (isDerivedArtifact returns true)
     }
-    // Read indexable documents for BM25 index
     const documentPromises = indexableFiles.map(async ({ mtime, path: filePath }) => {
         try {
-            const fullPath = join(contextTreePath, filePath);
+            const fullPath = join(origin.contextTreeRoot, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
             const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
-            return {
+            const qualifiedId = `${origin.originKey}::${filePath}`;
+            const symbolPath = getSymbolPath(origin, filePath);
+            // Check if a .overview.md sibling exists (written by abstract generation queue)
+            const overviewRelPath = filePath.replace(/\.md$/, OVERVIEW_EXTENSION);
+            const overviewPath = knownPaths.has(overviewRelPath) ? overviewRelPath : undefined;
+            const doc = {
                 content,
-                id: filePath,
+                id: qualifiedId,
                 mtime,
+                origin: origin.origin,
+                originContextTreeRoot: origin.contextTreeRoot,
+                originKey: origin.originKey,
+                ...(overviewPath !== undefined && { overviewPath }),
                 path: filePath,
                 scoring,
+                symbolPath,
                 title,
             };
+            if (origin.alias)
+                doc.originAlias = origin.alias;
+            return doc;
         }
         catch {
             return null;
         }
     });
-    // Read _index.md files separately for summaryMap (not indexed in BM25)
     const summaryPromises = summaryFiles.map(async ({ path: filePath }) => {
         try {
-            const fullPath = join(contextTreePath, filePath);
+            const fullPath = join(origin.contextTreeRoot, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const fm = parseSummaryFrontmatter(content);
             if (!fm)
                 return null;
+            // Persist frontmatter scoring so propagateScoresToParents can apply hotness/tier boosts
+            const frontmatter = parseFrontmatterScoring(content);
+            const scoring = frontmatter
+                ? { importance: frontmatter.importance, maturity: frontmatter.maturity, recency: frontmatter.recency }
+                : undefined;
             return {
                 condensationOrder: fm.condensation_order,
-                path: filePath,
+                excerpt: stripMarkdownFrontmatter(content).slice(0, 400),
+                path: getSymbolPath(origin, filePath),
+                scoring,
                 tokenCount: fm.token_count,
             };
         }
@@ -265,20 +369,18 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             return null;
         }
     });
-    const [docResults, summaryResults] = await Promise.all([
-        Promise.all(documentPromises),
-        Promise.all(summaryPromises),
-    ]);
+    const [docResults, summaryResults] = await Promise.all([Promise.all(documentPromises), Promise.all(summaryPromises)]);
     const documents = docResults.filter((doc) => doc !== null);
-    const documentMap = new Map();
     const fileMtimes = new Map();
     for (const doc of documents) {
-        documentMap.set(doc.id, doc);
-        fileMtimes.set(doc.path, doc.mtime);
+        fileMtimes.set(doc.id, doc.mtime);
     }
-    // Also track summary file mtimes for cache invalidation
     for (const sf of summaryFiles) {
-        fileMtimes.set(sf.path, sf.mtime);
+        fileMtimes.set(`${origin.originKey}::${sf.path}`, sf.mtime);
+    }
+    // Track .overview.md mtimes so the cache invalidates when a new overview is written
+    for (const ov of overviewFiles) {
+        fileMtimes.set(`${origin.originKey}::${ov.path}`, ov.mtime);
     }
     const summaryMap = new Map();
     for (const summary of summaryResults) {
@@ -286,28 +388,87 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             summaryMap.set(summary.path, summary);
         }
     }
+    return { documents, fileMtimes, summaryMap };
+}
+async function buildFreshIndex(fileSystem, contextTreePath, localFiles, sharedOrigins, sourcesFileMtime) {
+    const now = Date.now();
+    // Build the local origin descriptor.
+    // Note: `originKey: 'local'` is a string sentinel — shared origins use a 12-char
+    // SHA-256 hex hash from `deriveOriginKey()`. Consumers comparing originKey should
+    // treat 'local' as a reserved literal, not a hash.
+    const localOrigin = {
+        contextTreeRoot: contextTreePath,
+        origin: 'local',
+        originKey: 'local',
+    };
+    // Index local documents
+    const localResult = await indexOriginDocuments(fileSystem, localOrigin, localFiles);
+    // Index shared origin documents in parallel
+    const sharedResults = await Promise.all(sharedOrigins.map(async (origin) => {
+        try {
+            const files = await findMarkdownFilesWithMtime(fileSystem, origin.contextTreeRoot);
+            const filtered = files.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
+            return indexOriginDocuments(fileSystem, origin, filtered);
+        }
+        catch {
+            return { documents: [], fileMtimes: new Map(), summaryMap: new Map() };
+        }
+    }));
+    // Merge all documents, fileMtimes, and summaryMaps
+    const allDocuments = [...localResult.documents];
+    const fileMtimes = new Map(localResult.fileMtimes);
+    const summaryMap = new Map(localResult.summaryMap);
+    for (const result of sharedResults) {
+        allDocuments.push(...result.documents);
+        for (const [key, mtime] of result.fileMtimes) {
+            fileMtimes.set(key, mtime);
+        }
+        for (const [key, summary] of result.summaryMap) {
+            summaryMap.set(key, summary);
+        }
+    }
+    const documentMap = new Map();
+    const pathToDocumentId = new Map();
+    // Reverse lookup: symbolPath → document (for getSummarySource context.md fallback)
+    const symbolPathDocMap = new Map();
+    for (const doc of allDocuments) {
+        documentMap.set(doc.id, doc);
+        pathToDocumentId.set(doc.symbolPath, doc.id);
+        symbolPathDocMap.set(doc.symbolPath, doc);
+    }
     const index = new MiniSearch(MINISEARCH_OPTIONS);
-    index.addAll(documents);
-    // Build symbolic structures from the document map, with summary annotations
-    const symbolTree = buildSymbolTree(documentMap, summaryMap);
-    const referenceIndex = buildReferenceIndex(documentMap);
+    index.addAll(allDocuments);
+    const symbolDocumentMap = new Map();
+    for (const doc of allDocuments) {
+        symbolDocumentMap.set(doc.id, { ...doc, path: doc.symbolPath });
+    }
+    const symbolTree = buildSymbolTree(symbolDocumentMap, summaryMap);
+    // Reference index only uses local docs — cross-project references are not tracked
+    const referenceIndex = buildReferenceIndex(new Map(localResult.documents.map((doc) => [doc.id, doc])));
     return {
         contextTreePath,
         documentMap,
         fileMtimes,
         index,
         lastValidatedAt: now,
+        pathToDocumentId,
         referenceIndex,
         schemaVersion: INDEX_SCHEMA_VERSION,
+        sharedOrigins,
+        sourcesFileMtime,
         summaryMap,
+        symbolPathDocMap,
         symbolTree,
     };
 }
 /**
  * Acquires the search index, using cached data when valid or building a fresh index.
  * Uses promise-based locking to prevent duplicate builds during parallel execution.
+ *
+ * Self-loads knowledge sources from `.brv/sources.json` during each validation
+ * cycle, with mtime-based invalidation to detect source additions/removals.
  */
-async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeBuild) {
+async function acquireIndex(state, fileSystem, contextTreePath, baseDirectory, ttlMs, onBeforeBuild) {
     const now = Date.now();
     // Fast path: TTL-based cache hit (no I/O needed)
     if (state.cachedIndex &&
@@ -323,6 +484,23 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
     }
     // Create and store the build promise SYNCHRONOUSLY before any await
     // This prevents race conditions where multiple parallel calls all start building
+    const emptyResult = () => {
+        const emptyIndex = new MiniSearch(MINISEARCH_OPTIONS);
+        return {
+            contextTreePath: '',
+            documentMap: new Map(),
+            fileMtimes: new Map(),
+            index: emptyIndex,
+            lastValidatedAt: 0,
+            pathToDocumentId: new Map(),
+            referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            sharedOrigins: [],
+            summaryMap: new Map(),
+            symbolPathDocMap: new Map(),
+            symbolTree: { root: [], symbolMap: new Map() },
+        };
+    };
     const buildPromise = (async () => {
         // Check if context tree exists (only if no cache or different path)
         if (!state.cachedIndex || state.cachedIndex.contextTreePath !== contextTreePath) {
@@ -330,32 +508,55 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
                 await fileSystem.listDirectory(contextTreePath);
             }
             catch {
-                // Return empty index to signal error - caller will handle
-                const emptyIndex = new MiniSearch(MINISEARCH_OPTIONS);
-                return {
-                    contextTreePath: '',
-                    documentMap: new Map(),
-                    fileMtimes: new Map(),
-                    index: emptyIndex,
-                    lastValidatedAt: 0,
-                    referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
-                    schemaVersion: INDEX_SCHEMA_VERSION,
-                    summaryMap: new Map(),
-                    symbolTree: { root: [], symbolMap: new Map() },
-                };
+                return emptyResult();
             }
         }
-        const allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
+        // Self-load knowledge sources — mtime-based invalidation
+        const loadedSources = loadSources(baseDirectory);
+        const sourcesFileMtime = loadedSources?.mtime;
+        const sharedOrigins = loadedSources?.origins ?? [];
+        let allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
         // Exclude non-indexable derived artifacts (.full.md) so that currentFiles
         // matches what buildFreshIndex tracks in fileMtimes. Without this filter,
         // isCacheValid() sees a size mismatch once archives exist, causing cache thrash.
         // _index.md is kept (tracked for summary staleness), .stub.md is kept (BM25 indexed).
-        const currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
-        // Re-check cache validity after getting file list (another call may have finished)
-        if (state.cachedIndex &&
+        // Keep _index.md (summary tracking) and .overview.md (sibling detection for overviewPath).
+        // .full.md, .abstract.md, and _manifest.json remain excluded.
+        let localFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+            f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
+            f.path.endsWith(OVERVIEW_EXTENSION));
+        // Flush pending access hits before reusing a stale-enough cache entry.
+        // The flush updates frontmatter on disk, so refresh mtimes before the cache-valid check.
+        if (onBeforeBuild) {
+            const wroteScoringUpdates = await onBeforeBuild(contextTreePath);
+            if (wroteScoringUpdates) {
+                allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
+                localFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+                    f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
+                    f.path.endsWith(OVERVIEW_EXTENSION));
+            }
+        }
+        // Qualify local file mtime keys with 'local::' prefix to match buildFreshIndex
+        const qualifiedLocalFiles = localFiles.map((f) => ({ mtime: f.mtime, path: `local::${f.path}` }));
+        // Glob shared origin files for cache validation (detect edits in shared projects)
+        const sharedFileArrays = await Promise.all(sharedOrigins.map(async (origin) => {
+            try {
+                const files = await findMarkdownFilesWithMtime(fileSystem, origin.contextTreeRoot);
+                const filtered = files.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
+                return filtered.map((f) => ({ mtime: f.mtime, path: `${origin.originKey}::${f.path}` }));
+            }
+            catch {
+                return [];
+            }
+        }));
+        const allQualifiedFiles = [...qualifiedLocalFiles, ...sharedFileArrays.flat()];
+        // Re-check cache validity: local files + shared files + sources-file mtime must match
+        const sourcesFileChanged = state.cachedIndex?.sourcesFileMtime !== sourcesFileMtime;
+        if (!sourcesFileChanged &&
+            state.cachedIndex &&
             state.cachedIndex.contextTreePath === contextTreePath &&
             state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
-            isCacheValid(state.cachedIndex, currentFiles)) {
+            isCacheValid(state.cachedIndex, allQualifiedFiles)) {
             // Update timestamp atomically by creating a new object
             const updatedCache = {
                 ...state.cachedIndex,
@@ -364,12 +565,8 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
             state.cachedIndex = updatedCache;
             return updatedCache;
         }
-        // Flush pending access hits before building so updated scoring is picked up
-        if (onBeforeBuild) {
-            await onBeforeBuild(contextTreePath);
-        }
-        // Build fresh index
-        const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, currentFiles);
+        // Build fresh index with local + shared origins
+        const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, localFiles, sharedOrigins, sourcesFileMtime);
         state.cachedIndex = freshIndex;
         return freshIndex;
     })();
@@ -420,7 +617,7 @@ export class SearchKnowledgeService {
      */
     async flushAccessHits(contextTreePath) {
         if (this.pendingAccessHits.size === 0) {
-            return;
+            return false;
         }
         const hits = new Map(this.pendingAccessHits);
         this.pendingAccessHits.clear();
@@ -440,6 +637,7 @@ export class SearchKnowledgeService {
             }
         });
         await Promise.allSettled(tasks);
+        return true;
     }
     /**
      * Search the knowledge base for relevant topics.
@@ -451,14 +649,15 @@ export class SearchKnowledgeService {
      */
     async search(query, options) {
         const limit = options?.limit ?? 10;
-        const contextTreePath = join(this.baseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
+        const resolvedBaseDirectory = await realpath(this.baseDirectory).catch(() => this.baseDirectory);
+        const contextTreePath = join(resolvedBaseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
         // Acquire index with parallel-safe locking; flush pending access hits before any rebuild
-        const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.cacheTtlMs, (ctxPath) => this.flushAccessHits(ctxPath));
+        const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.baseDirectory, this.cacheTtlMs, (ctxPath) => this.flushAccessHits(ctxPath));
         // Handle error case (context tree not initialized)
         if ('error' in indexResult) {
             return indexResult.result;
         }
-        const { documentMap, index, referenceIndex, symbolTree } = indexResult;
+        const { documentMap, index, pathToDocumentId, referenceIndex, summaryMap, symbolPathDocMap, symbolTree } = indexResult;
         if (documentMap.size === 0) {
             return {
                 message: 'Context tree is empty. Use /curate to add knowledge.',
@@ -472,7 +671,7 @@ export class SearchKnowledgeService {
         }
         // Symbolic path resolution: try path-based query first
         if (isPathLikeQuery(query, symbolTree)) {
-            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options);
+            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, options);
             if (symbolicResult) {
                 return symbolicResult;
             }
@@ -482,10 +681,10 @@ export class SearchKnowledgeService {
         const effectiveScope = options?.scope ?? parsed.scopePath;
         const effectiveQuery = parsed.scopePath ? parsed.textQuery : query;
         // Run text-based MiniSearch (existing pipeline), optionally scoped to a subtree
-        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, symbolTree, referenceIndex, options);
+        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
         // If scoped search returned nothing and we had a scope, fall back to global search
         if (textResult.results.length === 0 && effectiveScope && effectiveQuery) {
-            return this.runTextSearch(query, documentMap, index, limit, undefined, symbolTree, referenceIndex, options);
+            return this.runTextSearch(query, documentMap, index, limit, undefined, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
         }
         return textResult;
     }
@@ -521,14 +720,15 @@ export class SearchKnowledgeService {
      * For archive stubs, extracts points_to path into archiveFullPath.
      */
     enrichResult(result, symbolTree, referenceIndex, documentMap) {
-        const symbol = symbolTree.symbolMap.get(result.path);
+        const doc = documentMap.get(result.id);
+        const symbolPath = doc?.symbolPath ?? result.path;
+        const symbol = symbolTree.symbolMap.get(symbolPath);
         const backlinks = referenceIndex.backlinks.get(result.path);
         // Detect archive stubs and extract points_to for drill-down
         let archiveFullPath;
         let symbolKind = symbol ? getSymbolKindLabel(symbol.kind) : undefined;
         if (isArchiveStub(result.path)) {
             symbolKind = 'archive_stub';
-            const doc = documentMap.get(result.path);
             if (doc) {
                 const stubFm = parseArchiveStubFrontmatter(doc.content);
                 if (stubFm) {
@@ -536,27 +736,51 @@ export class SearchKnowledgeService {
                 }
             }
         }
+        // Origin metadata for shared-source results
+        const origin = doc?.origin;
+        const originAlias = doc?.originAlias;
+        const originContextTreeRoot = doc?.origin === 'shared' ? doc.originContextTreeRoot : undefined;
+        const overviewPath = doc?.overviewPath;
+        const isContextSummary = doc?.path.endsWith('/context.md') || doc?.path === 'context.md';
+        const summaryPath = isContextSummary
+            ? doc?.path.slice(0, -'/context.md'.length) || doc?.path || result.path
+            : result.path;
+        // Destructure to strip `id` from output — not part of SearchKnowledgeResult
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { id: _id, ...rest } = result;
         return {
-            ...result,
+            ...rest,
             ...(archiveFullPath && { archiveFullPath }),
+            ...(overviewPath && { overviewPath }),
             backlinkCount: backlinks?.length ?? 0,
+            ...(origin && { origin }),
+            ...(originAlias && { originAlias }),
+            ...(originContextTreeRoot && { originContextTreeRoot }),
+            ...(isContextSummary && { path: summaryPath }),
             relatedPaths: backlinks?.slice(0, 3),
-            symbolKind,
-            symbolPath: symbol?.path,
+            symbolKind: isContextSummary ? 'summary' : symbolKind,
+            symbolPath: isContextSummary ? summaryPath : symbol?.path,
         };
     }
     /**
      * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
      */
-    runTextSearch(query, documentMap, index, limit, scopePath, symbolTree, referenceIndex, options) {
+    runTextSearch(query, documentMap, index, limit, scopePath, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options) {
         const filteredQuery = filterStopWords(query);
         const filteredWords = filteredQuery.split(/\s+/).filter((w) => w.length >= 2);
         // Build scope filter if a subtree is specified
         let scopeFilter;
         if (scopePath) {
-            const subtreeIds = getSubtreeDocumentIds(symbolTree, scopePath);
-            if (subtreeIds.size > 0) {
-                scopeFilter = (result) => subtreeIds.has(result.id);
+            const subtreePaths = getSubtreeDocumentIds(symbolTree, scopePath);
+            const subtreeQualifiedIds = new Set();
+            for (const symbolPath of subtreePaths) {
+                const docId = pathToDocumentId.get(symbolPath);
+                if (docId) {
+                    subtreeQualifiedIds.add(docId);
+                }
+            }
+            if (subtreeQualifiedIds.size > 0) {
+                scopeFilter = (result) => subtreeQualifiedIds.has(result.id);
             }
         }
         // AND-first strategy: for multi-word queries, try AND for concentrated scores.
@@ -576,6 +800,7 @@ export class SearchKnowledgeService {
         }
         // Normalize BM25 scores to [0, 1) then blend with importance + recency via compound scoring.
         // Decay is computed lazily from file mtime — no disk writes during search.
+        // Local results get a configurable score boost to prefer local knowledge over shared.
         const now = Date.now();
         const searchResults = rawResults.map((r) => {
             const doc = documentMap.get(r.id);
@@ -583,13 +808,21 @@ export class SearchKnowledgeService {
             const daysSince = doc ? Math.max(0, (now - doc.mtime) / 86_400_000) : 0;
             const decayed = applyDecay(scoring, daysSince);
             const bm25 = normalizeScore(r.score);
+            let finalScore = compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft');
+            // Local score boost: prefer local results over shared when scores are close
+            if (doc?.origin === 'local') {
+                finalScore = Math.min(finalScore + SHARED_SOURCE_LOCAL_SCORE_BOOST, 1);
+            }
             return {
                 ...r,
-                score: compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft'),
+                bm25Score: bm25,
+                score: finalScore,
             };
         });
         searchResults.sort((a, b) => b.score - a.score);
         const results = [];
+        const propagationInputs = [];
+        let scoreFloor;
         if (searchResults.length > 0) {
             // OOD detection: if the best result scores below the minimum floor,
             // the query has no meaningful match in the knowledge base.
@@ -615,7 +848,7 @@ export class SearchKnowledgeService {
                 };
             }
             const topScore = searchResults[0].score;
-            const scoreFloor = topScore * SCORE_GAP_RATIO;
+            scoreFloor = topScore * SCORE_GAP_RATIO;
             const resultLimit = Math.min(limit, searchResults.length);
             for (let i = 0; i < resultLimit; i++) {
                 const result = searchResults[i];
@@ -626,6 +859,7 @@ export class SearchKnowledgeService {
                 if (document) {
                     const enriched = this.enrichResult({
                         excerpt: extractExcerpt(document.content, query),
+                        id: result.id,
                         path: document.path,
                         score: Math.round(result.score * 100) / 100,
                         title: document.title,
@@ -638,22 +872,55 @@ export class SearchKnowledgeService {
                         continue;
                     }
                     if (options?.minMaturity && enriched.symbolKind) {
-                        const tierRank = { core: 3, draft: 1, validated: 2 };
-                        const symbol = symbolTree.symbolMap.get(document.path);
-                        const docMaturity = symbol?.metadata.maturity ?? 'draft';
-                        if ((tierRank[docMaturity] ?? 1) < (tierRank[options.minMaturity] ?? 1)) {
+                        const docMaturity = enriched.symbolKind === 'summary'
+                            ? (getSummarySource(enriched.path, summaryMap, symbolPathDocMap)?.scoring?.maturity ??
+                                symbolTree.symbolMap.get(enriched.path)?.metadata.maturity ??
+                                'draft')
+                            : (symbolTree.symbolMap.get(document.symbolPath)?.metadata.maturity ?? 'draft');
+                        if ((MATURITY_TIER_RANK[docMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1)) {
                             continue;
                         }
                     }
                     results.push(enriched);
+                    propagationInputs.push({
+                        bm25Score: result.bm25Score,
+                        path: document.symbolPath,
+                    });
                 }
             }
         }
-        // Accumulate access hits for returned results (flushed during next index rebuild)
-        // Disabled for benchmark: prevents feedback loop from distorting scores across queries
-        // if (results.length > 0) {
-        //   this.accumulateAccessHits(results.map((r) => r.path))
-        // }
+        // Propagate scores upward to parent domain/topic nodes (hierarchical retrieval)
+        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, symbolPathDocMap);
+        for (const p of propagated) {
+            // Apply local score boost to propagated summaries so they stay competitive
+            // with boosted direct BM25 hits (the boost was already applied to direct hits above)
+            p.score = Math.min(p.score + SHARED_SOURCE_LOCAL_SCORE_BOOST, 1);
+            if (scoreFloor !== undefined && p.score < scoreFloor)
+                continue;
+            if (options?.includeKinds && p.symbolKind && !options.includeKinds.includes(p.symbolKind))
+                continue;
+            if (options?.excludeKinds && p.symbolKind && options.excludeKinds.includes(p.symbolKind))
+                continue;
+            if (options?.minMaturity && p.symbolKind === 'summary') {
+                const summaryDoc = getSummarySource(p.path, summaryMap, symbolPathDocMap);
+                const summaryMaturity = summaryDoc?.scoring?.maturity ?? 'draft';
+                if ((MATURITY_TIER_RANK[summaryMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1))
+                    continue;
+            }
+            results.push(p);
+        }
+        if (propagated.length > 0) {
+            results.sort((a, b) => b.score - a.score);
+            // Trim back to the caller-requested limit after propagated entries are merged in.
+            if (results.length > limit)
+                results.splice(limit);
+        }
+        // Accumulate access hits for returned results (flushed during next index rebuild).
+        // Synthetic 'summary' results carry folder-style paths (e.g. 'auth') that are not
+        // real files; map them to their _index.md so flushAccessHits can read and update them.
+        if (results.length > 0) {
+            this.accumulateAccessHits(results.map((r) => r.symbolKind === 'summary' ? getSummaryAccessPath(r.path, summaryMap, symbolPathDocMap) : r.path));
+        }
         return {
             message: results.length > 0
                 ? `Found ${searchResults.length} result(s). Use read_file to view full content.`
@@ -665,7 +932,7 @@ export class SearchKnowledgeService {
     /**
      * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options) {
+    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, options) {
         const pathMatches = matchMemoryPath(symbolTree, query.split(/\s+/)[0].includes('/') ? query.split(/\s+/)[0] : query);
         if (pathMatches.length === 0) {
             return null;
@@ -673,12 +940,15 @@ export class SearchKnowledgeService {
         const topMatch = pathMatches[0].matchedSymbol;
         // If the matched symbol is a leaf Context, return it directly
         if (topMatch.kind === MemorySymbolKind.Context) {
-            const doc = documentMap.get(topMatch.path);
+            const docId = pathToDocumentId.get(topMatch.path);
+            const doc = docId ? documentMap.get(docId) : undefined;
             if (!doc) {
                 return null;
             }
-            const result = this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 1, title: doc.title }, symbolTree, referenceIndex, documentMap);
-            this.accumulateAccessHits([doc.path]);
+            const result = this.enrichResult({ excerpt: extractExcerpt(doc.content, query), id: doc.id, path: doc.path, score: 1, title: doc.title }, symbolTree, referenceIndex, documentMap);
+            if (doc.origin === 'local') {
+                this.accumulateAccessHits([doc.path]);
+            }
             return {
                 message: `Found exact match: ${topMatch.path}`,
                 results: [result],
@@ -691,21 +961,37 @@ export class SearchKnowledgeService {
         const textPart = query.slice(query.indexOf(pathPart) + pathPart.length).trim();
         if (textPart) {
             // Scoped search: search text within the matched subtree
-            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, symbolTree, referenceIndex, options);
+            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
         }
         // No text part — return all children of the matched node
         const subtreeIds = getSubtreeDocumentIds(symbolTree, topMatch.path);
         const results = [];
-        for (const docId of subtreeIds) {
+        const accessHitPaths = [];
+        const summaryDoc = getSummarySource(topMatch.path, summaryMap, symbolPathDocMap);
+        if (summaryDoc) {
+            results.push({
+                backlinkCount: 0,
+                excerpt: summaryDoc.excerpt,
+                path: topMatch.path,
+                score: 1,
+                symbolKind: 'summary',
+                symbolPath: topMatch.path,
+                title: topMatch.name,
+            });
+            accessHitPaths.push(summaryDoc.path);
+        }
+        for (const symbolPath of subtreeIds) {
             if (results.length >= limit)
                 break;
-            const doc = documentMap.get(docId);
+            const docId = pathToDocumentId.get(symbolPath);
+            const doc = docId ? documentMap.get(docId) : undefined;
             if (!doc)
                 continue;
-            results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex, documentMap));
+            results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), id: doc.id, path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex, documentMap));
+            accessHitPaths.push(doc.path);
         }
-        if (results.length > 0) {
-            this.accumulateAccessHits(results.map((r) => r.path));
+        if (accessHitPaths.length > 0) {
+            this.accumulateAccessHits(accessHitPaths);
         }
         return {
             message: `Found ${results.length} entries under ${topMatch.path}. Use read_file to view full content.`,