mustflow 1.18.0 → 1.18.14

package/dist/cli/lib/local-index.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
@@ -7,12 +7,20 @@ import { listFilesRecursive, toPosixPath } from './filesystem.js';
 import { readTomlFile } from './toml.js';
 import { collectSourceAnchorIndexRecords, } from '../../core/source-anchor-status.js';
 import { normalizeCommandEffects } from '../../core/command-effects.js';
-const LOCAL_INDEX_SCHEMA_VERSION = '7';
+import { listChangeClassificationRuleDescriptors } from '../../core/change-classification.js';
+const LOCAL_INDEX_SCHEMA_VERSION = '12';
+const LOCAL_INDEX_PARSER_VERSION = '1';
 const DEFAULT_DATABASE_RELATIVE_PATH = '.mustflow/cache/mustflow.sqlite';
 const LOCAL_INDEX_CONTENT_MODE = 'metadata_and_snippets';
 const LOCAL_INDEX_STORE_FULL_CONTENT = false;
 const MAX_SNIPPET_BYTES_PER_DOCUMENT = 2048;
+const SEARCH_NGRAM_MIN_LENGTH = 2;
+const SEARCH_NGRAM_MAX_LENGTH = 3;
+const SEARCH_BACKEND_FTS5 = 'fts5';
+const SEARCH_BACKEND_TABLE_SCAN = 'table_scan';
+const TEST_DISABLE_FTS5_ENV = 'MUSTFLOW_TEST_DISABLE_FTS5';
 const MUSTFLOW_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
+const INDEX_CONFIG_RELATIVE_PATH = '.mustflow/config/index.toml';
 const DEFAULT_PROMPT_CACHE_STABLE_READ = [
     'AGENTS.md',
     '.mustflow/docs/agent-workflow.md',
@@ -76,6 +84,14 @@ function readMustflowToml(projectRoot) {
     const parsed = readTomlFile(mustflowPath);
     return isRecord(parsed) ? parsed : undefined;
 }
+function readIndexToml(projectRoot) {
+    const indexConfigPath = path.join(projectRoot, ...INDEX_CONFIG_RELATIVE_PATH.split('/'));
+    if (!existsSync(indexConfigPath)) {
+        return undefined;
+    }
+    const parsed = readTomlFile(indexConfigPath);
+    return isRecord(parsed) ? parsed : undefined;
+}
 function readNestedTable(table, key) {
     if (!table || !isRecord(table[key])) {
         return undefined;
@@ -85,9 +101,39 @@ function readNestedTable(table, key) {
 function readOptionalStringArray(table, key) {
     return table ? readStringArray(table, key) ?? null : null;
 }
+function readBoolean(table, key) {
+    const value = table?.[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
+function readPositiveInteger(table, key) {
+    const value = table?.[key];
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        return null;
+    }
+    return value;
+}
+function readLocalIndexSourceConfig(projectRoot) {
+    const sourceIndexTable = readNestedTable(readIndexToml(projectRoot), 'source_index');
+    return {
+        enabledByDefault: readBoolean(sourceIndexTable, 'enabled_by_default') === true,
+        include: readOptionalStringArray(sourceIndexTable, 'include') ?? [],
+        exclude: readOptionalStringArray(sourceIndexTable, 'exclude') ?? [],
+        maxFileBytes: readPositiveInteger(sourceIndexTable, 'max_file_bytes'),
+        allowedExtensions: readOptionalStringArray(sourceIndexTable, 'allowed_extensions') ?? [],
+    };
+}
 function sha256Text(content) {
     return `sha256:${createHash('sha256').update(content).digest('hex')}`;
 }
+function sha256Bytes(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+function getSourceScopeHash(includeSource, sourceConfig) {
+    return sha256Text(JSON.stringify({
+        includeSource,
+        sourceConfig,
+    }));
+}
 function getDocumentType(relativePath) {
     if (relativePath === 'AGENTS.md') {
         return 'agent_rules';
@@ -268,6 +314,29 @@ function collectCommandIntents(projectRoot) {
     }
     return intents;
 }
+function readIndexedFileRecord(projectRoot, relativePath, sourceScope, contentHash = null) {
+    const fullPath = path.join(projectRoot, ...relativePath.split('/'));
+    const stats = statSync(fullPath);
+    return {
+        path: relativePath,
+        sourceScope,
+        sizeBytes: stats.size,
+        mtimeMs: Math.round(stats.mtimeMs),
+        contentHash: contentHash ?? sha256Bytes(readFileSync(fullPath)),
+    };
+}
+function collectIndexedFileRecords(projectRoot, documents, sourceAnchors) {
+    const records = new Map();
+    for (const document of documents) {
+        records.set(document.path, readIndexedFileRecord(projectRoot, document.path, 'workflow', document.contentHash));
+    }
+    for (const anchorPath of [...new Set(sourceAnchors.map((anchor) => anchor.path))].sort((left, right) => left.localeCompare(right))) {
+        if (!records.has(anchorPath)) {
+            records.set(anchorPath, readIndexedFileRecord(projectRoot, anchorPath, 'source_anchor'));
+        }
+    }
+    return [...records.values()].sort((left, right) => left.path.localeCompare(right.path));
+}
 async function loadSqlJs() {
     const require = createRequire(import.meta.url);
     const wasmPath = require.resolve('sql.js/dist/sql-wasm.wasm');
@@ -285,6 +354,28 @@ async function loadSqlJs() {
 function normalizeSearchText(value) {
     return value.trim().replace(/\s+/g, ' ');
 }
+function normalizeSearchTokenText(value) {
+    return normalizeSearchText(value).normalize('NFKC').toLowerCase();
+}
+function extractSearchTokens(value) {
+    return [...normalizeSearchTokenText(value).matchAll(/[\p{L}\p{N}]+/gu)]
+        .map((match) => match[0])
+        .filter((token) => Boolean(token));
+}
+function buildSearchNgrams(values) {
+    const grams = new Set();
+    for (const value of values) {
+        for (const token of extractSearchTokens(value)) {
+            const maxLength = Math.min(SEARCH_NGRAM_MAX_LENGTH, token.length);
+            for (let length = SEARCH_NGRAM_MIN_LENGTH; length <= maxLength; length += 1) {
+                for (let index = 0; index <= token.length - length; index += 1) {
+                    grams.add(token.slice(index, index + length));
+                }
+            }
+        }
+    }
+    return [...grams].sort((left, right) => left.localeCompare(right));
+}
 function toSearchString(value) {
     if (value === null || value === undefined) {
         return '';
@@ -307,12 +398,64 @@ function queryRows(database, sql, params = []) {
         return row;
     });
 }
+function searchCapabilities(fts5Available) {
+    return {
+        backend: fts5Available ? SEARCH_BACKEND_FTS5 : SEARCH_BACKEND_TABLE_SCAN,
+        fts5Available,
+    };
+}
+function detectLocalSearchCapabilities(database) {
+    if (process.env[TEST_DISABLE_FTS5_ENV] === '1') {
+        return searchCapabilities(false);
+    }
+    try {
+        database.run('CREATE VIRTUAL TABLE temp.mustflow_fts5_probe USING fts5(value)');
+        database.run('DROP TABLE temp.mustflow_fts5_probe');
+        return searchCapabilities(true);
+    }
+    catch {
+        return searchCapabilities(false);
+    }
+}
+function readMetadataValue(database, key) {
+    return toSearchString(queryRows(database, 'SELECT value FROM metadata WHERE key = ?', [key])[0]?.value) || undefined;
+}
+function hasTable(database, tableName) {
+    return queryRows(database, 'SELECT name FROM sqlite_master WHERE type = "table" AND name = ?', [tableName]).length > 0;
+}
+function readStoredSearchCapabilities(database) {
+    const fts5Available = readMetadataValue(database, 'search_fts5_available') === 'true';
+    const backend = readMetadataValue(database, 'search_backend');
+    if (backend === SEARCH_BACKEND_FTS5 && hasTable(database, 'search_documents_fts')) {
+        return { backend: SEARCH_BACKEND_FTS5, fts5Available };
+    }
+    return { backend: SEARCH_BACKEND_TABLE_SCAN, fts5Available };
+}
 function toNullableNumber(value) {
     if (typeof value !== 'number') {
         return null;
     }
     return Number.isFinite(value) ? value : null;
 }
+function splitIndexedList(value) {
+    return toSearchString(value)
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .sort((left, right) => left.localeCompare(right));
+}
+function createCommandEffectGraphStatus(databasePath, status, stalePaths = []) {
+    return {
+        source: 'local_index',
+        status,
+        databasePath,
+        indexFresh: status === 'fresh',
+        stalePaths,
+        writeLocks: [],
+        lockConflicts: [],
+        refreshHint: status === 'fresh' ? null : 'Run `mf index` to refresh command-effect graph explanations.',
+    };
+}
 async function readPreviousSourceAnchorSnapshots(databasePath) {
     if (!existsSync(databasePath)) {
         return [];
@@ -480,12 +623,18 @@ function sourceAnchorAuthority() {
 function getMatchSnippet(fields, query) {
     const normalized = normalizeSearchText(fields.join(' '));
     const lower = normalized.toLowerCase();
-    const start = lower.indexOf(query.toLowerCase());
+    let start = lower.indexOf(query.toLowerCase());
+    let matchLength = query.length;
     if (start === -1) {
-        return normalized.slice(0, 160);
+        const [firstGram] = buildSearchNgrams([query]).filter((gram) => lower.includes(gram));
+        if (!firstGram) {
+            return normalized.slice(0, 160);
+        }
+        start = lower.indexOf(firstGram);
+        matchLength = firstGram.length;
     }
     const from = Math.max(0, start - 48);
-    const to = Math.min(normalized.length, start + query.length + 96);
+    const to = Math.min(normalized.length, start + matchLength + 96);
     const prefix = from > 0 ? '...' : '';
     const suffix = to < normalized.length ? '...' : '';
     return `${prefix}${normalized.slice(from, to)}${suffix}`;
@@ -507,13 +656,24 @@ function isMatched(fields, query) {
     const lowerQuery = query.toLowerCase();
     return fields.some((field) => field.toLowerCase().includes(lowerQuery));
 }
-function createSchema(database) {
+function createSchema(database, capabilities) {
     database.run(`
 CREATE TABLE metadata (
   key TEXT PRIMARY KEY,
   value TEXT NOT NULL
 );
 
+CREATE TABLE indexed_files (
+  path TEXT PRIMARY KEY,
+  source_scope TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL,
+  mtime_ms INTEGER NOT NULL,
+  content_hash TEXT NOT NULL,
+  indexed_at TEXT NOT NULL,
+  index_mode TEXT NOT NULL,
+  parser_version TEXT NOT NULL
+);
+
 CREATE TABLE documents (
   path TEXT PRIMARY KEY,
   type TEXT NOT NULL,
@@ -538,6 +698,16 @@ CREATE TABLE document_terms (
   PRIMARY KEY (document_path, term, source)
 );
 
+CREATE TABLE search_ngrams (
+  target_kind TEXT NOT NULL,
+  target_key TEXT NOT NULL,
+  gram TEXT NOT NULL,
+  source TEXT NOT NULL,
+  PRIMARY KEY (target_kind, target_key, gram, source)
+);
+
+CREATE INDEX search_ngrams_lookup ON search_ngrams(target_kind, gram, target_key);
+
 CREATE TABLE skills (
   name TEXT PRIMARY KEY,
   path TEXT NOT NULL,
@@ -575,6 +745,62 @@ CREATE TABLE command_effects (
   PRIMARY KEY (intent, source, access, mode, path, lock, concurrency)
 );
 
+CREATE VIEW command_write_locks AS
+SELECT
+  intent,
+  lock,
+  group_concat(DISTINCT path) AS paths,
+  group_concat(DISTINCT mode) AS modes,
+  group_concat(DISTINCT source) AS sources,
+  group_concat(DISTINCT concurrency) AS concurrencies,
+  count(*) AS effect_count
+FROM command_effects
+WHERE access = 'write'
+GROUP BY intent, lock;
+
+CREATE VIEW command_lock_conflicts AS
+SELECT
+  a.intent AS left_intent,
+  b.intent AS right_intent,
+  a.lock AS lock,
+  group_concat(DISTINCT a.path) AS left_paths,
+  group_concat(DISTINCT b.path) AS right_paths,
+  group_concat(DISTINCT a.mode) AS left_modes,
+  group_concat(DISTINCT b.mode) AS right_modes,
+  group_concat(DISTINCT a.concurrency) AS left_concurrencies,
+  group_concat(DISTINCT b.concurrency) AS right_concurrencies
+FROM command_effects a
+JOIN command_effects b
+  ON a.lock = b.lock
+ AND a.intent < b.intent
+WHERE
+  a.access = 'write'
+  OR b.access = 'write'
+  OR a.concurrency = 'exclusive'
+  OR b.concurrency = 'exclusive'
+  OR a.mode = 'delete_recreate'
+  OR b.mode = 'delete_recreate'
+GROUP BY a.intent, b.intent, a.lock;
+
+CREATE TABLE path_surfaces (
+  rule_id TEXT PRIMARY KEY,
+  pattern_kind TEXT NOT NULL,
+  pattern TEXT NOT NULL,
+  pattern_flags TEXT NOT NULL,
+  surface_kind TEXT NOT NULL,
+  category TEXT NOT NULL,
+  is_public_surface INTEGER NOT NULL,
+  update_policy TEXT NOT NULL
+);
+
+CREATE TABLE path_surface_reasons (
+  rule_id TEXT NOT NULL,
+  reason_kind TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  ordinal INTEGER NOT NULL,
+  PRIMARY KEY (rule_id, reason_kind, reason)
+);
+
 CREATE TABLE source_anchors (
   id TEXT PRIMARY KEY,
   path TEXT NOT NULL,
@@ -621,6 +847,54 @@ CREATE TABLE source_anchor_status (
   can_instruct_agent INTEGER NOT NULL
 );
 `);
+    if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+        database.run(`
+CREATE VIRTUAL TABLE search_documents_fts USING fts5(
+  path UNINDEXED,
+  type UNINDEXED,
+  title,
+  sections,
+  terms,
+  snippet
+);
+
+CREATE VIRTUAL TABLE search_skills_fts USING fts5(
+  name UNINDEXED,
+  path UNINDEXED,
+  title
+);
+
+CREATE VIRTUAL TABLE search_skill_routes_fts USING fts5(
+  route_key UNINDEXED,
+  skill_name UNINDEXED,
+  skill_path UNINDEXED,
+  trigger,
+  required_input,
+  edit_scope,
+  risk,
+  verification_intents,
+  expected_output
+);
+
+CREATE VIRTUAL TABLE search_command_intents_fts USING fts5(
+  name UNINDEXED,
+  status UNINDEXED,
+  lifecycle UNINDEXED,
+  run_policy UNINDEXED,
+  description,
+  effects
+);
+
+CREATE VIRTUAL TABLE search_source_anchors_fts USING fts5(
+  id UNINDEXED,
+  path UNINDEXED,
+  purpose,
+  search_terms,
+  invariant,
+  risk
+);
+`);
+    }
 }
 function insertDocumentTerm(database, documentPath, term, source) {
     const normalized = normalizeSearchText(term ?? '');
@@ -633,8 +907,131 @@ function insertDocumentTerm(database, documentPath, term, source) {
         source,
     ]);
 }
-function populateDatabase(database, documents, skills, skillRoutes, commandIntents, sourceAnchors) {
+function insertSearchNgrams(database, targetKind, targetKey, values, source) {
+    for (const gram of buildSearchNgrams(values)) {
+        database.run('INSERT OR IGNORE INTO search_ngrams (target_kind, target_key, gram, source) VALUES (?, ?, ?, ?)', [targetKind, targetKey, gram, source]);
+    }
+}
+function insertPathSurfaceReasons(database, ruleId, reasonKind, values) {
+    values.forEach((value, index) => {
+        database.run('INSERT INTO path_surface_reasons (rule_id, reason_kind, reason, ordinal) VALUES (?, ?, ?, ?)', [ruleId, reasonKind, value, index + 1]);
+    });
+}
+function populatePathSurfaceReadModel(database) {
+    for (const rule of listChangeClassificationRuleDescriptors()) {
+        database.run('INSERT INTO path_surfaces (rule_id, pattern_kind, pattern, pattern_flags, surface_kind, category, is_public_surface, update_policy) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [
+            rule.id,
+            rule.patternKind,
+            rule.pattern,
+            rule.patternFlags,
+            rule.surface.kind,
+            rule.surface.category,
+            rule.surface.isPublicSurface ? 1 : 0,
+            rule.surface.updatePolicy,
+        ]);
+        insertPathSurfaceReasons(database, rule.id, 'change_kind', rule.changeKinds);
+        insertPathSurfaceReasons(database, rule.id, 'validation_reason', rule.surface.validationReasons);
+        insertPathSurfaceReasons(database, rule.id, 'affected_contract', rule.surface.affectedContracts);
+        insertPathSurfaceReasons(database, rule.id, 'drift_check', rule.surface.driftChecks);
+    }
+}
+function skillRouteKey(route) {
+    return `${route.skillName}\u0000${route.trigger}`;
+}
+function populateSearchTables(database, capabilities, documents, skills, skillRoutes, commandIntents, sourceAnchors) {
+    for (const document of documents) {
+        const documentTerms = queryRows(database, 'SELECT term FROM document_terms WHERE document_path = ? ORDER BY term', [
+            document.path,
+        ]).map((row) => toSearchString(row.term));
+        insertSearchNgrams(database, 'document', document.path, [
+            document.path,
+            document.type,
+            document.title,
+            document.sections.join(' '),
+            documentTerms.join(' '),
+            document.contentSnippet,
+        ], 'workflow_document');
+        if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+            database.run('INSERT INTO search_documents_fts (path, type, title, sections, terms, snippet) VALUES (?, ?, ?, ?, ?, ?)', [
+                document.path,
+                document.type,
+                document.title,
+                document.sections.join(' '),
+                documentTerms.join(' '),
+                document.contentSnippet,
+            ]);
+        }
+    }
+    for (const skill of skills) {
+        insertSearchNgrams(database, 'skill', skill.name, [skill.name, skill.path, skill.title], 'skill');
+        if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+            database.run('INSERT INTO search_skills_fts (name, path, title) VALUES (?, ?, ?)', [
+                skill.name,
+                skill.path,
+                skill.title,
+            ]);
+        }
+    }
+    for (const route of skillRoutes) {
+        const verificationIntents = route.verificationIntents.join(' ');
+        insertSearchNgrams(database, 'skill_route', skillRouteKey(route), [
+            skillRouteKey(route),
+            route.skillName,
+            route.skillPath,
+            route.trigger,
+            route.requiredInput,
+            route.editScope,
+            route.risk,
+            verificationIntents,
+            route.expectedOutput,
+        ], 'skill_route');
+        if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+            database.run('INSERT INTO search_skill_routes_fts (route_key, skill_name, skill_path, trigger, required_input, edit_scope, risk, verification_intents, expected_output) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)', [
+                skillRouteKey(route),
+                route.skillName,
+                route.skillPath,
+                route.trigger,
+                route.requiredInput,
+                route.editScope,
+                route.risk,
+                verificationIntents,
+                route.expectedOutput,
+            ]);
+        }
+    }
+    for (const intent of commandIntents) {
+        const effects = intent.effects
+            .flatMap((effect) => [effect.lock, effect.path, effect.mode, effect.access, effect.concurrency])
+            .join(' ');
+        insertSearchNgrams(database, 'command_intent', intent.name, [intent.name, intent.status, intent.lifecycle ?? '', intent.runPolicy ?? '', intent.description ?? '', effects], 'command_intent');
+        if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+            database.run('INSERT INTO search_command_intents_fts (name, status, lifecycle, run_policy, description, effects) VALUES (?, ?, ?, ?, ?, ?)', [intent.name, intent.status, intent.lifecycle, intent.runPolicy, intent.description, effects]);
+        }
+    }
+    for (const anchor of sourceAnchors) {
+        insertSearchNgrams(database, 'source_anchor', anchor.id, [
+            anchor.id,
+            anchor.path,
+            anchor.purpose ?? '',
+            anchor.search.join(' '),
+            anchor.invariant ?? '',
+            anchor.risk.join(' '),
+        ], 'source_anchor');
+        if (capabilities.backend === SEARCH_BACKEND_FTS5) {
+            database.run('INSERT INTO search_source_anchors_fts (id, path, purpose, search_terms, invariant, risk) VALUES (?, ?, ?, ?, ?, ?)', [
+                anchor.id,
+                anchor.path,
+                anchor.purpose,
+                anchor.search.join(' '),
+                anchor.invariant,
+                anchor.risk.join(' '),
+            ]);
+        }
+    }
+}
+function populateDatabase(database, capabilities, documents, skills, skillRoutes, commandIntents, sourceAnchors, indexedFiles, indexMode, sourceScopeHash, sourceIndexEnabled, indexedAt) {
     database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['schema_version', LOCAL_INDEX_SCHEMA_VERSION]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['parser_version', LOCAL_INDEX_PARSER_VERSION]);
     database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['content_mode', LOCAL_INDEX_CONTENT_MODE]);
     database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', [
         'store_full_content',
@@ -644,6 +1041,26 @@ function populateDatabase(database, documents, skills, skillRoutes, commandInten
         'max_snippet_bytes_per_document',
         String(MAX_SNIPPET_BYTES_PER_DOCUMENT),
     ]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['search_backend', capabilities.backend]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', [
+        'search_fts5_available',
+        String(capabilities.fts5Available),
+    ]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['source_scope_hash', sourceScopeHash]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['source_index_enabled', String(sourceIndexEnabled)]);
+    database.run('INSERT INTO metadata (key, value) VALUES (?, ?)', ['index_mode', indexMode]);
+    for (const indexedFile of indexedFiles) {
+        database.run('INSERT INTO indexed_files (path, source_scope, size_bytes, mtime_ms, content_hash, indexed_at, index_mode, parser_version) VALUES (?, ?, ?, ?, ?, ?, ?, ?)', [
+            indexedFile.path,
+            indexedFile.sourceScope,
+            indexedFile.sizeBytes,
+            indexedFile.mtimeMs,
+            indexedFile.contentHash,
+            indexedAt,
+            indexMode,
+            LOCAL_INDEX_PARSER_VERSION,
+        ]);
+    }
     for (const document of documents) {
         database.run('INSERT INTO documents (path, type, title, locale, revision, content_hash, content_snippet) VALUES (?, ?, ?, ?, ?, ?, ?)', [
             document.path,
@@ -743,29 +1160,110 @@ function populateDatabase(database, documents, skills, skillRoutes, commandInten
             anchor.canInstructAgent ? 1 : 0,
         ]);
     }
+    populatePathSurfaceReadModel(database);
+    populateSearchTables(database, capabilities, documents, skills, skillRoutes, commandIntents, sourceAnchors);
+}
+function indexedFilesMatch(database, currentFiles) {
+    const rows = queryRows(database, 'SELECT path, source_scope, content_hash, parser_version FROM indexed_files ORDER BY path');
+    if (rows.length !== currentFiles.length) {
+        return false;
+    }
+    const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
+    for (const row of rows) {
+        const storedPath = toSearchString(row.path);
+        const current = currentByPath.get(storedPath);
+        if (!current) {
+            return false;
+        }
+        if (toSearchString(row.source_scope) !== current.sourceScope ||
+            toSearchString(row.content_hash) !== current.contentHash ||
+            toSearchString(row.parser_version) !== LOCAL_INDEX_PARSER_VERSION) {
+            return false;
+        }
+    }
+    return true;
+}
+async function readIncrementalReuseDecision(SQL, databasePath, currentFiles, sourceScopeHash) {
+    if (!existsSync(databasePath)) {
+        return { reusable: false, rebuildReason: 'missing_index', capabilities: null };
+    }
+    let database;
+    try {
+        database = new SQL.Database(readFileSync(databasePath));
+        if (readStoredSchemaVersion(database) !== LOCAL_INDEX_SCHEMA_VERSION) {
+            return { reusable: false, rebuildReason: 'schema_version_mismatch', capabilities: null };
+        }
+        if (readMetadataValue(database, 'parser_version') !== LOCAL_INDEX_PARSER_VERSION) {
+            return { reusable: false, rebuildReason: 'parser_version_mismatch', capabilities: null };
+        }
+        if (readMetadataValue(database, 'source_scope_hash') !== sourceScopeHash) {
+            return { reusable: false, rebuildReason: 'source_scope_mismatch', capabilities: null };
+        }
+        if (!hasTable(database, 'indexed_files')) {
+            return { reusable: false, rebuildReason: 'indexed_files_missing', capabilities: null };
+        }
+        if (!indexedFilesMatch(database, currentFiles)) {
+            return { reusable: false, rebuildReason: 'file_fingerprint_mismatch', capabilities: null };
+        }
+        return {
+            reusable: true,
+            rebuildReason: null,
+            capabilities: readStoredSearchCapabilities(database),
+        };
+    }
+    catch {
+        return { reusable: false, rebuildReason: 'unreadable_index', capabilities: null };
+    }
+    finally {
+        database?.close();
+    }
 }
 /**
  * mf:anchor cli.index.create
  * purpose: Build the local SQLite index for workflow documents and optional source anchors.
  * search: mf index, local index, sqlite, source anchors, workflow documents
- * invariant: Source anchors are indexed only when source indexing is explicitly requested.
+ * invariant: Source anchors are indexed only when requested by CLI flag or local index configuration.
  * risk: cache, config
  */
 export async function createLocalIndex(projectRoot, options = {}) {
     const databasePath = getLocalIndexDatabasePath(projectRoot);
+    const dryRun = options.dryRun === true;
+    const incremental = options.incremental === true;
+    const indexMode = incremental ? 'incremental' : 'full';
     const documents = collectDocuments(projectRoot);
     const skills = collectSkills(documents);
     const skillRoutes = collectSkillRoutes(projectRoot);
     const commandIntents = collectCommandIntents(projectRoot);
-    const includeSource = options.includeSource === true;
-    const previousSourceAnchors = includeSource ? await readPreviousSourceAnchorSnapshots(databasePath) : [];
-    const sourceAnchors = includeSource ? collectSourceAnchorIndexRecords(projectRoot, previousSourceAnchors) : [];
-    const dryRun = options.dryRun === true;
-    if (!dryRun) {
-        const SQL = await loadSqlJs();
+    const sourceConfig = readLocalIndexSourceConfig(projectRoot);
+    const includeSource = options.includeSource === true || sourceConfig.enabledByDefault;
+    const sourceScopeHash = getSourceScopeHash(includeSource, sourceConfig);
+    const previousSourceAnchors = includeSource
+        ? await readPreviousSourceAnchorSnapshots(databasePath).catch(() => [])
+        : [];
+    const sourceAnchors = includeSource
+        ? collectSourceAnchorIndexRecords(projectRoot, previousSourceAnchors, {
+            ...sourceConfig,
+            excludeGeneratedOrVendor: true,
+        })
+        : [];
+    const indexedFiles = collectIndexedFileRecords(projectRoot, documents, sourceAnchors);
+    let capabilities = searchCapabilities(false);
+    let reusedExisting = false;
+    let rebuildReason = null;
+    const SQL = await loadSqlJs();
+    const capabilityDatabase = new SQL.Database();
+    capabilities = detectLocalSearchCapabilities(capabilityDatabase);
+    capabilityDatabase.close();
+    if (incremental) {
+        const reuseDecision = await readIncrementalReuseDecision(SQL, databasePath, indexedFiles, sourceScopeHash);
+        reusedExisting = reuseDecision.reusable;
+        rebuildReason = reuseDecision.rebuildReason;
+        capabilities = reuseDecision.capabilities ?? capabilities;
+    }
+    if (!dryRun && !reusedExisting) {
         const database = new SQL.Database();
-        createSchema(database);
-        populateDatabase(database, documents, skills, skillRoutes, commandIntents, sourceAnchors);
+        createSchema(database, capabilities);
+        populateDatabase(database, capabilities, documents, skills, skillRoutes, commandIntents, sourceAnchors, indexedFiles, indexMode, sourceScopeHash, includeSource, new Date().toISOString());
         mkdirSync(path.dirname(databasePath), { recursive: true });
         writeFileSync(databasePath, database.export());
         database.close();
@@ -777,7 +1275,10 @@ export async function createLocalIndex(projectRoot, options = {}) {
         mustflow_root: path.resolve(projectRoot),
         database_path: databasePath,
         dry_run: dryRun,
-        wrote_files: !dryRun,
+        wrote_files: !dryRun && !reusedExisting,
+        index_mode: indexMode,
+        reused_existing: reusedExisting,
+        rebuild_reason: rebuildReason,
         document_count: documents.length,
         skill_count: skills.length,
         skill_route_count: skillRoutes.length,
@@ -785,20 +1286,47 @@ export async function createLocalIndex(projectRoot, options = {}) {
         command_effect_count: commandIntents.reduce((count, intent) => count + intent.effects.length, 0),
         source_index_enabled: includeSource,
         source_anchor_count: sourceAnchors.length,
+        search_backend: capabilities.backend,
+        search_fts5_available: capabilities.fts5Available,
         content_mode: LOCAL_INDEX_CONTENT_MODE,
         store_full_content: LOCAL_INDEX_STORE_FULL_CONTENT,
         max_snippet_bytes_per_document: MAX_SNIPPET_BYTES_PER_DOCUMENT,
+        indexed_file_count: indexedFiles.length,
         indexed_paths: documents.map((document) => document.path),
     };
 }
 function readStoredSchemaVersion(database) {
-    return toSearchString(queryRows(database, 'SELECT value FROM metadata WHERE key = "schema_version"')[0]?.value) || undefined;
+    return readMetadataValue(database, 'schema_version');
 }
 function getStalePaths(projectRoot, database) {
     const schemaVersion = readStoredSchemaVersion(database);
     if (schemaVersion !== LOCAL_INDEX_SCHEMA_VERSION) {
         return ['.mustflow/cache/mustflow.sqlite'];
     }
+    if (hasTable(database, 'indexed_files')) {
+        const stalePaths = new Set();
+        const indexedRows = queryRows(database, 'SELECT path, source_scope, content_hash FROM indexed_files');
+        const indexedPaths = new Set(indexedRows.map((row) => toSearchString(row.path)));
+        for (const row of indexedRows) {
+            const indexedPath = toSearchString(row.path);
+            const sourceScope = toSearchString(row.source_scope) === 'source_anchor' ? 'source_anchor' : 'workflow';
+            try {
+                const current = readIndexedFileRecord(projectRoot, indexedPath, sourceScope);
+                if (current.contentHash !== toSearchString(row.content_hash)) {
+                    stalePaths.add(indexedPath);
+                }
+            }
+            catch {
+                stalePaths.add(indexedPath);
+            }
+        }
+        for (const document of collectDocuments(projectRoot)) {
+            if (!indexedPaths.has(document.path)) {
+                stalePaths.add(document.path);
+            }
+        }
+        return Array.from(stalePaths).sort((left, right) => left.localeCompare(right));
+    }
     const indexedRows = queryRows(database, 'SELECT path, content_hash FROM documents');
     const indexedHashes = new Map(indexedRows.map((row) => [toSearchString(row.path), toSearchString(row.content_hash)]));
     const currentDocuments = collectDocuments(projectRoot);
@@ -816,6 +1344,258 @@ function getStalePaths(projectRoot, database) {
     }
     return Array.from(stalePaths).sort((left, right) => left.localeCompare(right));
 }
+function mapCommandLockConflict(row, intent) {
+    const targetIsLeft = toSearchString(row.left_intent) === intent;
+    const targetPrefix = targetIsLeft ? 'left' : 'right';
+    const otherPrefix = targetIsLeft ? 'right' : 'left';
+    return {
+        intent: toSearchString(row[`${otherPrefix}_intent`]),
+        lock: toSearchString(row.lock),
+        paths: splitIndexedList(row[`${targetPrefix}_paths`]),
+        modes: splitIndexedList(row[`${targetPrefix}_modes`]),
+        concurrencies: splitIndexedList(row[`${targetPrefix}_concurrencies`]),
+        conflictingPaths: splitIndexedList(row[`${otherPrefix}_paths`]),
+        conflictingModes: splitIndexedList(row[`${otherPrefix}_modes`]),
+        conflictingConcurrencies: splitIndexedList(row[`${otherPrefix}_concurrencies`]),
+    };
+}
+/**
+ * mf:anchor cli.index.command-effect-graph
+ * purpose: Read command-effect lock and conflict explanations from the local SQLite index.
+ * search: mf explain command, command locks, local index, sqlite graph
+ * invariant: Indexed command-effect rows explain current commands.toml only when the index is fresh and never grant command authority.
+ * risk: cache, config
+ */
+function queryLocalCommandEffectGraph(databasePath, database, intent) {
+    const writeLocks = queryRows(database, `
+SELECT lock, paths, modes, sources, concurrencies, effect_count
+FROM command_write_locks
+WHERE intent = ?
+ORDER BY lock
+`, [intent]).map((row) => ({
+        lock: toSearchString(row.lock),
+        paths: splitIndexedList(row.paths),
+        modes: splitIndexedList(row.modes),
+        sources: splitIndexedList(row.sources),
+        concurrencies: splitIndexedList(row.concurrencies),
+        effectCount: typeof row.effect_count === 'number' && Number.isFinite(row.effect_count) ? row.effect_count : 0,
+    }));
+    const lockConflicts = queryRows(database, `
+SELECT
+  left_intent,
+  right_intent,
+  lock,
+  left_paths,
+  right_paths,
+  left_modes,
+  right_modes,
+  left_concurrencies,
+  right_concurrencies
+FROM command_lock_conflicts
+WHERE left_intent = ? OR right_intent = ?
+ORDER BY lock, left_intent, right_intent
+`, [intent, intent]).map((row) => mapCommandLockConflict(row, intent));
+    return {
+        source: 'local_index',
+        status: 'fresh',
+        databasePath,
+        indexFresh: true,
+        stalePaths: [],
+        writeLocks,
+        lockConflicts,
+        refreshHint: null,
+    };
+}
+export async function readLocalCommandEffectGraph(projectRoot, intent) {
+    const graphs = await readLocalCommandEffectGraphs(projectRoot, [intent]);
+    return graphs.get(intent) ?? createCommandEffectGraphStatus(getLocalIndexDatabasePath(projectRoot), 'unreadable');
+}
+export async function readLocalCommandEffectGraphs(projectRoot, intents) {
+    const databasePath = getLocalIndexDatabasePath(projectRoot);
+    const intentNames = [...new Set(intents)];
+    const statusMap = (status, stalePaths = []) => new Map(intentNames.map((intent) => [intent, createCommandEffectGraphStatus(databasePath, status, stalePaths)]));
+    if (!existsSync(databasePath)) {
+        return statusMap('missing');
+    }
+    const SQL = await loadSqlJs();
+    const database = new SQL.Database(readFileSync(databasePath));
+    try {
+        const stalePaths = getStalePaths(projectRoot, database);
+        if (stalePaths.length > 0) {
+            return statusMap('stale', stalePaths);
+        }
+        return new Map(intentNames.map((intent) => [intent, queryLocalCommandEffectGraph(databasePath, database, intent)]));
+    }
+    catch {
+        return statusMap('unreadable');
+    }
+    finally {
+        database.close();
+    }
+}
+function createPathSurfaceReadModelStatus(databasePath, status, inputPath, stalePaths = []) {
+    return {
+        source: 'local_index',
+        status,
+        databasePath,
+        indexFresh: status === 'fresh',
+        stalePaths,
+        inputPath,
+        match: null,
+        refreshHint: status === 'fresh' ? null : 'Run `mf index` to refresh path-surface explanations.',
+    };
+}
+function createLocalIndexPromptContextStatus(databasePath, status, stalePaths = [], capabilities = null) {
+    return {
+        source: 'local_index',
+        status,
+        databasePath,
+        indexFresh: status === 'fresh',
+        stalePaths,
+        searchBackend: capabilities?.backend ?? null,
+        searchFts5Available: capabilities?.fts5Available ?? null,
+        refreshHint: status === 'fresh' ? null : 'Run `mf index` to refresh prompt-cache task context local-index metadata.',
+    };
+}
+export async function readLocalIndexPromptContext(projectRoot) {
+    const databasePath = getLocalIndexDatabasePath(projectRoot);
+    if (!existsSync(databasePath)) {
+        return createLocalIndexPromptContextStatus(databasePath, 'missing');
+    }
+    let database;
+    try {
+        const SQL = await loadSqlJs();
+        database = new SQL.Database(readFileSync(databasePath));
+        const capabilities = readStoredSearchCapabilities(database);
+        const stalePaths = getStalePaths(projectRoot, database);
+        if (stalePaths.length > 0) {
+            return createLocalIndexPromptContextStatus(databasePath, 'stale', stalePaths, capabilities);
+        }
+        return createLocalIndexPromptContextStatus(databasePath, 'fresh', [], capabilities);
+    }
+    catch {
+        return createLocalIndexPromptContextStatus(databasePath, 'unreadable');
+    }
+    finally {
+        database?.close();
+    }
+}
+function pathSurfaceReadModelWithMatch(base, match) {
+    return {
+        ...base,
+        match,
+    };
+}
+function readPathSurfaceReasonMap(database) {
+    const byRule = new Map();
+    for (const row of queryRows(database, 'SELECT rule_id, reason_kind, reason FROM path_surface_reasons ORDER BY rule_id, reason_kind, ordinal')) {
+        const ruleId = toSearchString(row.rule_id);
+        const reasonKind = toSearchString(row.reason_kind);
+        const reason = toSearchString(row.reason);
+        let reasonsByKind = byRule.get(ruleId);
+        if (!reasonsByKind) {
+            reasonsByKind = new Map();
+            byRule.set(ruleId, reasonsByKind);
+        }
+        const reasons = reasonsByKind.get(reasonKind) ?? [];
+        reasons.push(reason);
+        reasonsByKind.set(reasonKind, reasons);
+    }
+    return byRule;
+}
+function readPathSurfaceRuleMatches(database) {
+    const reasons = readPathSurfaceReasonMap(database);
+    return queryRows(database, 'SELECT rule_id, pattern_kind, pattern, pattern_flags, surface_kind, category, is_public_surface, update_policy FROM path_surfaces ORDER BY rowid').map((row) => {
+        const ruleId = toSearchString(row.rule_id);
+        const reasonsByKind = reasons.get(ruleId);
+        const reasonList = (kind) => reasonsByKind?.get(kind) ?? [];
+        return {
+            ruleId,
+            patternKind: toSearchString(row.pattern_kind),
+            pattern: toSearchString(row.pattern),
+            patternFlags: toSearchString(row.pattern_flags),
+            changeKinds: reasonList('change_kind'),
+            surface: {
+                kind: toSearchString(row.surface_kind),
+                category: toSearchString(row.category),
+                isPublicSurface: Number(row.is_public_surface) === 1,
+                validationReasons: reasonList('validation_reason'),
+                affectedContracts: reasonList('affected_contract'),
+                updatePolicy: toSearchString(row.update_policy),
+                driftChecks: reasonList('drift_check'),
+            },
+        };
+    });
+}
+function matchPathSurfaceRule(relativePath, rules) {
+    if (!relativePath) {
+        return null;
+    }
+    for (const rule of rules) {
+        try {
+            if (new RegExp(rule.pattern, rule.patternFlags).test(relativePath)) {
+                return rule;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export async function readLocalPathSurfaces(projectRoot, relativePaths) {
+    const databasePath = getLocalIndexDatabasePath(projectRoot);
+    const normalizedPaths = [...new Set(relativePaths.map((relativePath) => toPosixPath(relativePath)).filter(Boolean))];
+    const statusMap = (status, stalePaths = []) => new Map(normalizedPaths.map((relativePath) => [
+        relativePath,
+        createPathSurfaceReadModelStatus(databasePath, status, relativePath, stalePaths),
+    ]));
+    if (!existsSync(databasePath)) {
+        return statusMap('missing');
+    }
+    const SQL = await loadSqlJs();
+    const database = new SQL.Database(readFileSync(databasePath));
+    try {
+        const stalePaths = getStalePaths(projectRoot, database);
+        if (stalePaths.length > 0) {
+            return statusMap('stale', stalePaths);
+        }
+        const rules = readPathSurfaceRuleMatches(database);
+        return new Map(normalizedPaths.map((relativePath) => {
+            const base = createPathSurfaceReadModelStatus(databasePath, 'fresh', relativePath);
+            return [relativePath, pathSurfaceReadModelWithMatch(base, matchPathSurfaceRule(relativePath, rules))];
+        }));
+    }
+    catch {
+        return statusMap('unreadable');
+    }
+    finally {
+        database.close();
+    }
+}
+export async function readLocalPathSurface(projectRoot, relativePath) {
+    const databasePath = getLocalIndexDatabasePath(projectRoot);
+    const inputPath = relativePath ? toPosixPath(relativePath) : null;
+    if (!inputPath) {
+        if (!existsSync(databasePath)) {
+            return createPathSurfaceReadModelStatus(databasePath, 'missing', null);
+        }
+        const SQL = await loadSqlJs();
+        const database = new SQL.Database(readFileSync(databasePath));
+        try {
+            const stalePaths = getStalePaths(projectRoot, database);
+            return createPathSurfaceReadModelStatus(databasePath, stalePaths.length > 0 ? 'stale' : 'fresh', null, stalePaths);
+        }
+        catch {
+            return createPathSurfaceReadModelStatus(databasePath, 'unreadable', null);
+        }
+        finally {
+            database.close();
+        }
+    }
+    const surfaces = await readLocalPathSurfaces(projectRoot, [inputPath]);
+    return surfaces.get(inputPath) ?? createPathSurfaceReadModelStatus(databasePath, 'unreadable', inputPath);
+}
 function getSectionHeadings(database, documentPath) {
     return queryRows(database, 'SELECT heading FROM sections WHERE document_path = ? ORDER BY ordinal', [documentPath]).map((row) => toSearchString(row.heading));
 }
@@ -833,6 +1613,94 @@ function getCommandEffects(database, intent) {
         concurrency: toSearchString(row.concurrency),
     }));
 }
+const EMPTY_INDEXED_SEARCH_MATCHES = {
+    active: false,
+    documents: new Set(),
+    skills: new Set(),
+    skillRoutes: new Set(),
+    commandIntents: new Set(),
+    sourceAnchors: new Set(),
+};
+function buildFtsQuery(query) {
+    const tokens = extractSearchTokens(query);
+    if (tokens.length === 0) {
+        return null;
+    }
+    return [...new Set(tokens)].map((token) => `"${token.replaceAll('"', '""')}"`).join(' AND ');
+}
+function queryFtsSet(database, sql, ftsQuery, column) {
+    return new Set(queryRows(database, sql, [ftsQuery]).map((row) => toSearchString(row[column])));
+}
+function mergeSearchSets(left, right) {
+    return new Set([...left, ...right]);
+}
+function mergeIndexedSearchMatches(left, right) {
+    return {
+        active: left.active || right.active,
+        documents: mergeSearchSets(left.documents, right.documents),
+        skills: mergeSearchSets(left.skills, right.skills),
+        skillRoutes: mergeSearchSets(left.skillRoutes, right.skillRoutes),
+        commandIntents: mergeSearchSets(left.commandIntents, right.commandIntents),
+        sourceAnchors: mergeSearchSets(left.sourceAnchors, right.sourceAnchors),
+    };
+}
+function queryNgramSet(database, targetKind, grams) {
+    const placeholders = grams.map(() => '?').join(', ');
+    if (!placeholders) {
+        return new Set();
+    }
+    return new Set(queryRows(database, `SELECT target_key
+FROM search_ngrams
+WHERE target_kind = ? AND gram IN (${placeholders})
+GROUP BY target_key
+HAVING COUNT(DISTINCT gram) = ?`, [targetKind, ...grams, grams.length]).map((row) => toSearchString(row.target_key)));
+}
+function getNgramSearchMatches(database, query) {
+    if (!hasTable(database, 'search_ngrams')) {
+        return EMPTY_INDEXED_SEARCH_MATCHES;
+    }
+    const grams = buildSearchNgrams([query]);
+    if (grams.length === 0) {
+        return EMPTY_INDEXED_SEARCH_MATCHES;
+    }
+    return {
+        active: true,
+        documents: queryNgramSet(database, 'document', grams),
+        skills: queryNgramSet(database, 'skill', grams),
+        skillRoutes: queryNgramSet(database, 'skill_route', grams),
+        commandIntents: queryNgramSet(database, 'command_intent', grams),
+        sourceAnchors: queryNgramSet(database, 'source_anchor', grams),
+    };
+}
+function getIndexedSearchMatches(database, query) {
+    const capabilities = readStoredSearchCapabilities(database);
+    const ftsQuery = capabilities.backend === SEARCH_BACKEND_FTS5 ? buildFtsQuery(query) : null;
+    const ngramMatches = getNgramSearchMatches(database, query);
+    if (!ftsQuery) {
+        return ngramMatches;
+    }
+    try {
+        const ftsMatches = {
+            active: true,
+            documents: queryFtsSet(database, 'SELECT path FROM search_documents_fts WHERE search_documents_fts MATCH ?', ftsQuery, 'path'),
+            skills: queryFtsSet(database, 'SELECT name FROM search_skills_fts WHERE search_skills_fts MATCH ?', ftsQuery, 'name'),
+            skillRoutes: queryFtsSet(database, 'SELECT route_key FROM search_skill_routes_fts WHERE search_skill_routes_fts MATCH ?', ftsQuery, 'route_key'),
+            commandIntents: queryFtsSet(database, 'SELECT name FROM search_command_intents_fts WHERE search_command_intents_fts MATCH ?', ftsQuery, 'name'),
+            sourceAnchors: queryFtsSet(database, 'SELECT id FROM search_source_anchors_fts WHERE search_source_anchors_fts MATCH ?', ftsQuery, 'id'),
+        };
+        return mergeIndexedSearchMatches(ftsMatches, ngramMatches);
+    }
+    catch {
+        return ngramMatches;
+    }
+}
+function matchesIndexedOrTableScan(fields, query, indexedMatches, matchSet, key) {
+    return (indexedMatches.active && matchSet.has(key)) || isMatched(fields, query);
+}
+function scoreIndexedOrTableScan(primaryFields, secondaryFields, query, indexedMatches, matchSet, key) {
+    const tableScore = scoreMatch(primaryFields, secondaryFields, query);
+    return indexedMatches.active && matchSet.has(key) ? Math.max(tableScore, 20) : tableScore;
+}
 /**
  * mf:anchor cli.search.local-index
  * purpose: Search the local index while preserving workflow authority above source navigation hints.
@@ -854,9 +1722,12 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
     const SQL = await loadSqlJs();
     const database = new SQL.Database(readFileSync(databasePath));
     const cacheLayers = readCacheLayerSets(projectRoot);
+    let capabilities = searchCapabilities(false);
     const results = [];
     try {
         const stalePaths = getStalePaths(projectRoot, database);
+        capabilities = readStoredSearchCapabilities(database);
+        const indexedMatches = getIndexedSearchMatches(database, normalizedQuery);
         if (stalePaths.length > 0) {
             throw new Error(`Local mustflow index is stale: ${stalePaths.join(', ')}. Run \`mf index\` before searching. Refresh command: mf index`);
         }
@@ -870,7 +1741,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const documentTerms = getDocumentTerms(database, pathValue);
                 const primaryFields = [pathValue, title];
                 const secondaryFields = [typeValue, contentSnippet, ...sectionHeadings, ...documentTerms];
-                if (!isMatched([...primaryFields, ...secondaryFields], normalizedQuery)) {
+                const fields = [...primaryFields, ...secondaryFields];
+                if (!matchesIndexedOrTableScan(fields, normalizedQuery, indexedMatches, indexedMatches.documents, pathValue)) {
                     continue;
                 }
                 results.push(withCacheHint({
@@ -879,8 +1751,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                     title,
                     document_type: typeValue,
                     ...workflowAuthorityForDocument(typeValue),
-                    match: getMatchSnippet([...primaryFields, ...secondaryFields], normalizedQuery),
-                    score: scoreMatch(primaryFields, secondaryFields, normalizedQuery),
+                    match: getMatchSnippet(fields, normalizedQuery),
+                    score: scoreIndexedOrTableScan(primaryFields, secondaryFields, normalizedQuery, indexedMatches, indexedMatches.documents, pathValue),
                 }, cacheLayers));
             }
             for (const row of queryRows(database, 'SELECT name, path, title FROM skills')) {
@@ -888,7 +1760,7 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const pathValue = toSearchString(row.path);
                 const title = toSearchString(row.title);
                 const fields = [name, pathValue, title];
-                if (!isMatched(fields, normalizedQuery)) {
+                if (!matchesIndexedOrTableScan(fields, normalizedQuery, indexedMatches, indexedMatches.skills, name)) {
                     continue;
                 }
                 results.push(withCacheHint({
@@ -898,7 +1770,7 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                     title,
                     ...skillAuthority(),
                     match: getMatchSnippet(fields, normalizedQuery),
-                    score: scoreMatch([name, pathValue, title], [], normalizedQuery),
+                    score: scoreIndexedOrTableScan([name, pathValue, title], [], normalizedQuery, indexedMatches, indexedMatches.skills, name),
                 }, cacheLayers));
             }
             for (const row of queryRows(database, 'SELECT skill_name, skill_path, trigger, required_input, edit_scope, risk, verification_intents, expected_output FROM skill_routes')) {
@@ -912,7 +1784,9 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const expectedOutput = toSearchString(row.expected_output);
                 const primaryFields = [name, trigger];
                 const secondaryFields = [pathValue, requiredInput, editScope, risk, expectedOutput];
-                if (!isMatched([...primaryFields, ...secondaryFields], normalizedQuery)) {
+                const fields = [...primaryFields, ...secondaryFields];
+                const routeKey = skillRouteKey({ skillName: name, trigger });
+                if (!matchesIndexedOrTableScan(fields, normalizedQuery, indexedMatches, indexedMatches.skillRoutes, routeKey)) {
                     continue;
                 }
                 results.push(withCacheHint({
@@ -924,8 +1798,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                     route_risk: risk,
                     verification_intents: verificationIntents,
                     ...skillAuthority(),
-                    match: getMatchSnippet([...primaryFields, ...secondaryFields], normalizedQuery),
-                    score: scoreMatch(primaryFields, secondaryFields, normalizedQuery),
+                    match: getMatchSnippet(fields, normalizedQuery),
+                    score: scoreIndexedOrTableScan(primaryFields, secondaryFields, normalizedQuery, indexedMatches, indexedMatches.skillRoutes, routeKey),
                 }, cacheLayers));
             }
             for (const row of queryRows(database, 'SELECT name, status, lifecycle, run_policy, description FROM command_intents')) {
@@ -940,7 +1814,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const effectModes = [...new Set(effects.map((effect) => effect.mode))].sort((left, right) => left.localeCompare(right));
                 const primaryFields = [name];
                 const secondaryFields = [status, lifecycle, runPolicy, description, ...effectLocks, ...effectPaths, ...effectModes];
-                if (!isMatched([...primaryFields, ...secondaryFields], normalizedQuery)) {
+                const fields = [...primaryFields, ...secondaryFields];
+                if (!matchesIndexedOrTableScan(fields, normalizedQuery, indexedMatches, indexedMatches.commandIntents, name)) {
                     continue;
                 }
                 results.push(withCacheHint({
@@ -951,8 +1826,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                     effect_paths: effectPaths,
                     effect_modes: effectModes,
                     ...commandIntentAuthority(),
-                    match: getMatchSnippet([...primaryFields, ...secondaryFields], normalizedQuery),
-                    score: scoreMatch(primaryFields, secondaryFields, normalizedQuery),
+                    match: getMatchSnippet(fields, normalizedQuery),
+                    score: scoreIndexedOrTableScan(primaryFields, secondaryFields, normalizedQuery, indexedMatches, indexedMatches.commandIntents, name),
                 }, cacheLayers));
             }
         }
@@ -966,7 +1841,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                 const risk = toSearchString(row.risk);
                 const primaryFields = [id, pathValue];
                 const secondaryFields = [purpose, searchTerms, invariant, risk];
-                if (!isMatched([...primaryFields, ...secondaryFields], normalizedQuery)) {
+                const fields = [...primaryFields, ...secondaryFields];
+                if (!matchesIndexedOrTableScan(fields, normalizedQuery, indexedMatches, indexedMatches.sourceAnchors, id)) {
                     continue;
                 }
                 results.push(withCacheHint({
@@ -980,8 +1856,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
                     ...sourceAnchorAuthority(),
                     stale_status: toSearchString(row.status),
                     stale_confidence: Number(row.confidence),
-                    match: getMatchSnippet([...primaryFields, ...secondaryFields], normalizedQuery),
-                    score: scoreMatch(primaryFields, secondaryFields, normalizedQuery),
+                    match: getMatchSnippet(fields, normalizedQuery),
+                    score: scoreIndexedOrTableScan(primaryFields, secondaryFields, normalizedQuery, indexedMatches, indexedMatches.sourceAnchors, id),
                 }, cacheLayers));
             }
         }
@@ -1008,6 +1884,8 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
         scope,
         index_fresh: true,
         stale_paths: [],
+        search_backend: capabilities.backend,
+        search_fts5_available: capabilities.fts5Available,
         result_count: sortedResults.length,
         results: sortedResults,
     };