@nomos-arc/arc 0.1.0

package/docs/phase7/plan.md

@@ -0,0 +1,1682 @@
+# Atomic Implementation Blueprint — Phase 7: Global Semantic Search (Remediated)
+
+**Source Specification:** `docs/phase7/task.md`
+**Red Team Audit:** `docs/phase7/TEAM_RED.md`
+**Predecessor Phases:** 0–6 (complete). `project_map.json` and `*.semantic.md` files exist.
+**Status:** Ready for execution — all Critical Blockers neutralized.
+
+---
+
+## 0. Executive Summary of Fixes
+
+Every finding from the Red Team Adversarial Audit has been addressed. The following table maps each finding to its resolution in this remediated plan.
+
+### Critical Blockers — Neutralized
+
+| Finding | Original Flaw | Resolution | Location |
+|---|---|---|---|
+| **BLOCKER-1** | `reset()` + `upsert()` not atomic — zero-availability window | **Table-swap strategy**: full re-index writes to `nomos_vectors_tmp`, then drops old table and renames. Search always hits a live table. | Step 7.1.1 |
+| **BLOCKER-2** | `index-meta.json` written after vector upsert — crash leaves inconsistent state | **Status field**: metadata written at start with `status: "in_progress"`, updated to `"complete"` after upsert. On startup with `in_progress`, force full re-index. | Steps 7.0.5, 7.4.1 |
+| **BLOCKER-3** | No vector dimension validation on incremental index | **Dimension guard**: incremental flow step 2 compares `IndexMetadata.embedding_model` + `vector_dimensions` against current config. Mismatch → forced full re-index with warning. | Step 7.4.1 |
+| **BLOCKER-4** | All vectors accumulated in memory before upsert | **Streaming batch upsert**: after each embedding batch completes, compose records and upsert immediately. References released per-batch. | Step 7.4.1 |
+
+### Ambiguity Traps — Eliminated
+
+| Finding | Original Flaw | Resolution | Location |
+|---|---|---|---|
+| **TRAP-1** | `mergeInsert` fallback strategy undefined | **Explicit version detection**: check for `mergeInsert` method existence on table prototype at init time. Store capability flag. Fallback uses single-transaction `overwrite` mode, not delete-then-add. | Step 7.1.1 |
+| **TRAP-2** | `max_concurrent_requests` contradicts "process sequentially" | **Removed `max_concurrent_requests`**. Replaced with `embedding_requests_per_minute` (rate limiter). Batches processed sequentially with delay. One config, one behavior. | Step 7.0.4 |
+| **TRAP-3** | De-duplication logic vague ("takes priority") | **Hard rule**: if a symbol result and its parent file result are both present and within 0.05 absolute similarity, **remove the file-level result**. Keep only the more specific symbol result. | Step 7.5.2 |
+| **TRAP-4** | `graph_depth: -1` sentinel leaks to CLI output | **Stale result handling**: results with `graph_depth === -1` display `"⚠ Stale — file removed since last index"` instead of depth. No negative numbers in output. | Steps 7.5.1, 7.6.2 |
+| **TRAP-5** | `.semantic.md` path derivation fragile for multi-extension files | **Lookup via `project_map.json` `semantic` field**: if `FileNode.semantic` is non-null, the data is inline — no file read needed. If null, skip `.semantic.md` read entirely. No regex-based path derivation. | Step 7.3.1 |
+
+### Resilience Gaps — Sealed
+
+| Finding | Original Flaw | Resolution | Location |
+|---|---|---|---|
+| **GAP-1** | Partial embedding failure → permanent blind spots | **`failed_files: string[]`** in `IndexMetadata`. Incremental index treats failed files as "changed" regardless of hash. Cleared on successful re-embed. | Steps 7.0.5, 7.4.1 |
+| **GAP-2** | LanceDB corruption / version mismatch undetected | **`lancedb.connect()` wrapped in try-catch** with actionable error: `"Vector index corrupted. Run: arc index --force"`. **LanceDB pinned to exact version** (`"0.14.3"`, not `"^0.14.3"`). | Steps 7.0.1, 7.1.1 |
+| **GAP-3** | SIGINT between `reset()` and `upsert()` → unrecoverable empty store | **Eliminated by table-swap** (BLOCKER-1 fix). SIGINT during indexing leaves the old table intact. Temp table is orphaned but harmless — cleaned up on next index run. | Step 7.4.1 |
+| **GAP-4** | No timeout on Gemini API calls | **30-second `AbortController` timeout** on every embedding request. Timeout throws `NomosError('search_embedding_failed', 'Embedding request timed out after 30s')`. | Step 7.2.1 |
+| **GAP-5** | `project_map.json` loaded on every search query | **Lazy-loaded and cached** in `GraphEnricher`. Parsed once per `QueryEngine` instance lifetime. For CLI usage (one search per process), this eliminates redundant parsing. | Step 7.5.1 |
+
+### Secondary Concerns — Addressed
+
+| Finding | Resolution | Location |
+|---|---|---|
+| **S-1** | PF-5 changed: if `src/search/` exists, verify known files present (idempotent re-entry). | Pre-Flight |
+| **S-2** | `arc index --dry-run` added — extracts and counts chunks without embedding or writing. | Step 7.6.1 |
+| **S-3** | Distance-to-similarity conversion centralized in `VectorStore.query()`. Assertion: returned similarity ∈ [0, 1]. | Step 7.1.1 |
+| **S-4** | Mock-embedder integration test added — runs in CI with deterministic fake vectors. | Step 7.7.1 |
+| **S-5** | `SearchResult` type excludes `vector` field. JSON output verified to not leak raw vectors. | Step 7.0.5 |
+| **S-6** | `content_hash` computed from raw inputs (file path + semantic data + symbol signatures), not composed text. | Step 7.3.1 |
+| **S-7** | Build script modification reads current script, inserts `--external` flags before `--banner`. | Step 7.0.2 |
+| **S-8** | Rate limit delays logged: `"[nomos:search:warn] Rate limited. Waiting {N}ms before next batch..."`. | Step 7.2.1 |
+
+---
+
+## 1. Pre-Flight Checklist
+
+Every check must pass before execution begins. Failure on any check = STOP.
+
+| # | Check | Command | Expected |
+|---|-------|---------|----------|
+| PF-1 | Node.js >= 20 | `node --version` | Output starts with `v20` or higher |
+| PF-2 | Project root valid | `ls package.json src/cli.ts` | Both exist, exit code 0 |
+| PF-3 | Clean dependency install | `npm install` | Exit code 0 |
+| PF-4 | Existing tests pass | `npx vitest run` | 0 failures |
+| PF-5 | `src/search/` is either absent OR contains Phase 7 files | `ls src/search/vector-store.ts 2>&1` | Either "No such file" (fresh) OR file exists (re-entry). If `src/search/` exists but `vector-store.ts` does not → STOP: unknown directory, investigate. |
+| PF-6 | `project_map.json` exists | `ls tasks-management/graph/project_map.json` | File exists |
+| PF-7 | Git working tree clean | `git status --porcelain` | Empty output (or acknowledged untracked) |
+| PF-8 | `GEMINI_API_KEY` set | `echo $GEMINI_API_KEY \| head -c 5` | Non-empty (first 5 chars visible) |
+| PF-9 | Existing graph module intact | `ls src/core/graph/pipeline.ts` | File exists, exit code 0 |
+| PF-10 | Build script readable | `node -e "const p=JSON.parse(require('fs').readFileSync('package.json'));console.log(p.scripts.build.includes('--banner'))"` | `true` — confirms `--banner` flag exists as insertion anchor |
+
+---
+
+## 2. Atomic Execution Sequence
+
+---
+
+### Task 7.0: Prerequisites — Dependencies & Configuration
+
+---
+
+#### Step 7.0.1: Install LanceDB (Pinned Version)
+
+**Pre-Condition:** PF-1 through PF-7 pass. `package.json` exists at project root.
+
+**Action:**
+```bash
+npm install @lancedb/lancedb@0.14.3 apache-arrow@18.1.0
+```
+
+**Why pinned versions (M-9):** LanceDB is pre-1.0. No semver stability guarantees. A minor version bump could change the on-disk format, break the Arrow schema, or alter the `mergeInsert` API. Apache Arrow is pinned as its peer dependency for schema compatibility.
+
+**Post-install:** Manually edit `package.json` to ensure the version specifiers are exact (`"0.14.3"`, not `"^0.14.3"`). `npm install` by default writes `^` — this MUST be stripped.
+
+**Validation:**
+```bash
+node -e "import('@lancedb/lancedb').then(()=>console.log('ok'))"    # → "ok"
+node -e "import('apache-arrow').then(()=>console.log('ok'))"        # → "ok"
+grep '"@lancedb/lancedb": "0.14.3"' package.json                    # → exact match (no ^)
+grep '"apache-arrow": "18.1.0"' package.json                        # → exact match (no ^)
+```
+
+**Rollback:** `npm uninstall @lancedb/lancedb apache-arrow`
+
+**Idempotency:** `npm install` with already-installed packages is a no-op. Version pin check is idempotent.
+
+---
+
+#### Step 7.0.2: Update esbuild externals
+
+**Pre-Condition:** Step 7.0.1 complete. `package.json` `build` script exists.
+
+**Action:** Read the current `build` script from `package.json`. Locate the `--banner:js=` flag. Insert `--external:@lancedb/lancedb --external:apache-arrow` immediately **before** the `--banner` flag. This preserves argument ordering and avoids breaking existing esbuild flag positions.
+
+Do NOT blindly append to the end of the script string.
+
+**Validation:**
+```bash
+grep 'external:@lancedb/lancedb' package.json  # → match
+grep 'external:apache-arrow' package.json       # → match
+npm run build                                   # → exit code 0
+node dist/cli.js --help                         # → shows help without crash
+```
+
+**Rollback:** `git checkout package.json && npm install`
+
+**Idempotency:** Check if `--external:@lancedb/lancedb` already exists in the build script before modifying.
+
+---
+
+#### Step 7.0.3: Add new `NomosErrorCode` values
+
+**Pre-Condition:** `src/core/errors.ts` exists. Contains `NomosErrorCode` union type.
+
+**Action:** Add six new error code literals to the `NomosErrorCode` union type, immediately after `'graph_write_failed'`:
+```typescript
+| 'search_index_not_found'
+| 'search_index_failed'
+| 'search_index_corrupted'
+| 'search_embedding_failed'
+| 'search_query_failed'
+| 'search_api_key_missing'
+```
+
+Note: `search_index_corrupted` is new (addresses GAP-2 — explicit error code for corrupted/unreadable vector store).
+
+**Validation:**
+```bash
+grep 'search_index_not_found' src/core/errors.ts   # → exactly 1 match
+grep 'search_index_corrupted' src/core/errors.ts    # → exactly 1 match
+npx tsc --noEmit                                    # → exit code 0
+```
+
+**Rollback:** `git checkout src/core/errors.ts`
+
+**Idempotency:** Check if `'search_index_not_found'` already exists before inserting. If present, skip.
+
+---
+
+#### Step 7.0.4: Extend `NomosConfig` with `search` section
+
+**Pre-Condition:** `src/core/config.ts` and `src/types/index.ts` exist.
+
+**Action (types/index.ts):** Add `search` section to the `NomosConfig` interface:
+```typescript
+search: {
+  embedding_model: string;
+  embedding_dimensions: number;
+  vector_store_path: string;
+  default_top_k: number;
+  default_threshold: number;
+  batch_size: number;
+  embedding_requests_per_minute: number;
+  request_timeout_ms: number;
+};
+```
+
+**TRAP-2 resolution:** `max_concurrent_requests` is **removed**. It implied concurrent batch processing, but the embedder processes sequentially with rate-limit delays. A dead config that implies a non-existent capability is worse than no config. Replaced by `embedding_requests_per_minute` (already present) and `request_timeout_ms` (new, addresses GAP-4).
+
+**Action (config.ts):** Add `SearchConfigSchema` and register it in `NomosConfigSchema`:
+```typescript
+const SearchConfigSchema = z.object({
+  embedding_model: z.string().default('gemini-embedding-001'),
+  embedding_dimensions: z.number().int().positive().default(768),
+  vector_store_path: z.string().default('tasks-management/graph/vector_index'),
+  default_top_k: z.number().int().positive().default(5),
+  default_threshold: z.number().min(0).max(1).default(0.7),
+  batch_size: z.number().int().positive().max(100).default(50),
+  embedding_requests_per_minute: z.number().int().positive().default(300),
+  request_timeout_ms: z.number().int().positive().default(30_000),
+});
+```
+
+Add to `NomosConfigSchema`:
+```typescript
+search: SearchConfigSchema.default(() => SearchConfigSchema.parse({})),
+```
+
+**Validation:**
+```bash
+npx tsc --noEmit                               # → exit code 0
+npx vitest run                                  # → 0 failures (no regressions)
+node -e "
+  import { NomosConfigSchema } from './src/core/config.js';
+  const c = NomosConfigSchema.parse({});
+  console.log(c.search.embedding_model);        // → 'gemini-embedding-001'
+  console.log(c.search.default_top_k);          // → 5
+  console.log(c.search.embedding_dimensions);   // → 768
+  console.log(c.search.request_timeout_ms);     // → 30000
+  console.log(Object.keys(c.search).includes('max_concurrent_requests'));  // → false
+"
+```
+
+**Rollback:** `git checkout src/core/config.ts src/types/index.ts`
+
+**Idempotency:** Check if `SearchConfigSchema` already exists before adding.
+
+---
+
+#### Step 7.0.5: Add search types to `types/index.ts`
+
+**Pre-Condition:** Step 7.0.4 complete.
+
+**Action:** Append new type definitions to `src/types/index.ts`:
+
+```typescript
+// ─── Semantic Search Types ──────────────────────────────────────────────────
+
+export type ChunkType = 'file' | 'symbol';
+
+export interface TextChunk {
+  id: string;                          // "src/foo.ts" or "src/foo.ts::MyClass"
+  type: ChunkType;
+  file_path: string;
+  text: string;                        // concatenated searchable text
+  symbol_name: string | null;          // non-null for symbol-level chunks
+  symbol_type: string | null;          // 'function' | 'class' | etc.
+  line_start: number | null;
+  line_end: number | null;
+  parent_file_id: string | null;       // for symbol chunks, points to parent file chunk
+  content_hash: string;                // SHA-256 of raw inputs (NOT composed text) [S-6]
+}
+
+export interface VectorRecord {
+  id: string;
+  type: ChunkType;
+  vector: Float32Array;
+  file_path: string;
+  module: string;                      // directory name or logical module
+  purpose: string;
+  symbol_name: string | null;
+  symbol_type: string | null;
+  line_start: number | null;
+  line_end: number | null;
+  parent_file_id: string | null;
+  graph_depth: number;
+  dependents_count: number;
+  last_indexed: string;                // ISO 8601
+  content_hash: string;                // SHA-256 of raw inputs
+}
+
+/**
+ * SearchResult — returned to consumers.
+ * CRITICAL [S-5]: Does NOT include `vector` field.
+ * JSON.stringify(SearchResult) must never leak raw Float32Array data.
+ */
+export interface SearchResult {
+  id: string;
+  type: ChunkType;
+  file_path: string;
+  symbol_name: string | null;
+  symbol_type: string | null;
+  line_start: number | null;
+  line_end: number | null;
+  purpose: string;
+  similarity_score: number;            // always in [0, 1] — enforced by VectorStore.query()
+  graph_depth: number;                 // -1 = stale (file deleted since last index)
+  dependents_count: number;
+  is_core_module: boolean;
+  is_stale: boolean;                   // true when graph_depth === -1 [TRAP-4]
+}
+
+export type IndexStatus = 'in_progress' | 'complete';
+
+export interface IndexMetadata {
+  status: IndexStatus;                 // [BLOCKER-2] written at start and end of indexing
+  last_full_index: string;             // ISO 8601
+  last_incremental_index: string | null;
+  total_files_indexed: number;
+  total_symbols_indexed: number;
+  total_chunks: number;
+  embedding_model: string;             // [BLOCKER-3] compared on incremental index
+  vector_dimensions: number;           // [BLOCKER-3] compared on incremental index
+  failed_files: string[];              // [GAP-1] files that failed embedding — re-indexed next run
+  files: Record<string, {
+    last_indexed: string;
+    content_hash: string;
+    chunk_count: number;
+  }>;
+}
+```
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `git checkout src/types/index.ts`
+
+**Idempotency:** Check if `ChunkType` already exists before appending.
+
+---
+
+#### Step 7.0.6: Update `.gitignore`
+
+**Pre-Condition:** `.gitignore` exists at project root.
+
+**Action:** Append the following lines to `.gitignore` (if not already present):
+```
+# Phase 7: Vector search index (local, regenerable)
+tasks-management/graph/vector_index/
+```
+
+**Validation:**
+```bash
+grep 'vector_index' .gitignore  # → match
+```
+
+**Rollback:** Remove the added lines from `.gitignore`.
+
+**Idempotency:** Grep for `vector_index` before appending. If present, skip.
+
+---
+
+### Task 7.1: Vector Store — LanceDB Interface (Table-Swap Architecture)
+
+---
+
+#### Step 7.1.1: Create `src/search/vector-store.ts`
+
+**Pre-Condition:** Step 7.0.1–7.0.5 complete. `@lancedb/lancedb` installed. Types defined.
+
+**Action:** Create `src/search/vector-store.ts` implementing the `VectorStore` class.
+
+**Class API:**
+
+```typescript
+export class VectorStore {
+  private db: Connection | null = null;
+  private hasMergeInsert: boolean = false;  // [TRAP-1] detected at init
+
+  constructor(
+    private readonly storePath: string,
+    private readonly logger: Logger,
+  );
+
+  /** Initialize the DB connection. Detects mergeInsert capability. [GAP-2] wrapped in try-catch. */
+  async init(): Promise<void>;
+
+  /**
+   * Upsert a batch of vector records into the LIVE table.
+   * Uses mergeInsert if available; otherwise overwrites by id.
+   * Called per-batch during indexing [BLOCKER-4] — NOT after accumulating all records.
+   */
+  async upsert(records: VectorRecord[]): Promise<void>;
+
+  /**
+   * Write records to a TEMPORARY table for full re-index [BLOCKER-1].
+   * Does NOT touch the live table. Called per-batch.
+   */
+  async upsertToStaging(records: VectorRecord[]): Promise<void>;
+
+  /**
+   * Atomic table swap: drop live table, rename staging → live [BLOCKER-1].
+   * If swap fails, the live table remains untouched.
+   */
+  async promoteStagingToLive(): Promise<void>;
+
+  /** Drop the staging table if it exists (cleanup after failed index). */
+  async cleanupStaging(): Promise<void>;
+
+  /**
+   * Query the LIVE table with a vector. Returns top-K results above threshold.
+   * Cosine distance → similarity conversion happens HERE and ONLY here [S-3].
+   * Returns similarity_score ∈ [0, 1] — asserted before return.
+   */
+  async query(
+    vector: Float32Array,
+    topK: number,
+    threshold: number,
+  ): Promise<Array<Omit<VectorRecord, 'vector'> & { similarity_score: number }>>;
+
+  /**
+   * Delete all records whose file_path matches any of the given paths.
+   * Used for incremental re-indexing: delete stale → upsert fresh.
+   */
+  async deleteByFilePaths(filePaths: string[]): Promise<void>;
+
+  /** Return total record count in live table. */
+  async count(): Promise<number>;
+}
+```
+
+**Internal Design:**
+
+1. **Connection [GAP-2]:**
+   ```typescript
+   async init(): Promise<void> {
+     try {
+       this.db = await lancedb.connect(this.storePath);
+     } catch (err) {
+       throw new NomosError(
+         'search_index_corrupted',
+         `Failed to open vector store at ${this.storePath}. ` +
+         `The index may be corrupted. Run: arc index --force\n` +
+         `Original error: ${err instanceof Error ? err.message : String(err)}`
+       );
+     }
+     // [TRAP-1] Detect mergeInsert capability
+     try {
+       const names = await this.db.tableNames();
+       if (names.includes(LIVE_TABLE)) {
+         const table = await this.db.openTable(LIVE_TABLE);
+         this.hasMergeInsert = typeof table.mergeInsert === 'function';
+       }
+     } catch {
+       this.hasMergeInsert = false;
+     }
+   }
+   ```
+
+2. **Table names:**
+   ```typescript
+   const LIVE_TABLE = 'nomos_vectors';
+   const STAGING_TABLE = 'nomos_vectors_staging';
+   ```
+
+3. **Full re-index flow [BLOCKER-1] — Table-swap strategy:**
+   - Indexer calls `cleanupStaging()` at start (remove orphaned staging table from prior crash).
+   - For each embedding batch, indexer calls `upsertToStaging(batchRecords)`.
+   - After all batches complete, indexer calls `promoteStagingToLive()`.
+   - `promoteStagingToLive()` implementation:
+     ```typescript
+     async promoteStagingToLive(): Promise<void> {
+       const names = await this.db!.tableNames();
+       if (!names.includes(STAGING_TABLE)) {
+         throw new NomosError('search_index_failed', 'Staging table does not exist. Index may have failed.');
+       }
+       // Drop old live table if it exists
+       if (names.includes(LIVE_TABLE)) {
+         await this.db!.dropTable(LIVE_TABLE);
+       }
+       // Rename staging → live
+       // LanceDB does not have a native rename. Workaround:
+       // Read all from staging, create new live table, drop staging.
+       const staging = await this.db!.openTable(STAGING_TABLE);
+       const allData = await staging.query().toArray();
+       await this.db!.createTable(LIVE_TABLE, allData, { mode: 'overwrite' });
+       await this.db!.dropTable(STAGING_TABLE);
+     }
+     ```
+   - **SIGINT safety [GAP-3]:** If SIGINT fires during indexing, the live table is never touched (staging is the only write target). On next run, `cleanupStaging()` removes the orphaned staging table.
+
+4. **Upsert strategy [TRAP-1]:**
+   - If `hasMergeInsert === true`: use `table.mergeInsert('id')` for incremental upserts to the live table.
+   - If `hasMergeInsert === false`: use `table.overwrite(records)` which atomically replaces all data. For incremental upserts, fall back to: read existing data into memory, merge by `id`, then `overwrite`. This is safe because incremental re-indexes only change a subset of files.
+   - **No delete-then-add fallback.** Delete-then-add creates a window where records are missing.
+
+5. **Query with centralized distance conversion [S-3]:**
+   ```typescript
+   async query(vector, topK, threshold): Promise<...> {
+     const table = await this.db!.openTable(LIVE_TABLE);
+     const raw = await table.vectorSearch(vector)
+       .distanceType('cosine')
+       .limit(topK * 2)   // over-fetch to allow post-filter
+       .toArray();
+
+     return raw
+       .map(r => {
+         const similarity = 1 - r._distance;
+         // [S-3] Assert similarity ∈ [0, 1]
+         const clamped = Math.max(0, Math.min(1, similarity));
+         return { ...r, similarity_score: clamped, vector: undefined };
+       })
+       .filter(r => r.similarity_score >= threshold)
+       .slice(0, topK);
+   }
+   ```
+   The `vector` field is stripped from query results — it MUST NOT appear in any output.
+
+**Validation:**
+```bash
+npx tsc --noEmit                        # → exit code 0
+# Unit test (Step 7.1.2):
+npx vitest run src/search/__tests__/vector-store.test.ts
+```
+
+**Rollback:** `rm src/search/vector-store.ts`
+
+---
+
+#### Step 7.1.2: Unit test for `VectorStore`
+
+**Pre-Condition:** Step 7.1.1 complete.
+
+**Action:** Create `src/search/__tests__/vector-store.test.ts`.
+
+**Test cases:**
+1. `init()` creates the DB directory if it does not exist.
+2. `init()` wraps connection failure in `NomosError('search_index_corrupted')` [GAP-2].
+3. `upsert()` inserts records; `count()` returns correct total.
+4. `upsert()` with duplicate `id` overwrites (not duplicates) — regardless of `mergeInsert` availability.
+5. `query()` returns results ranked by cosine similarity (closest first).
+6. `query()` with threshold filters out low-similarity results.
+7. `query()` returns `similarity_score` ∈ [0, 1] — never negative, never > 1 [S-3].
+8. `query()` results do NOT contain `vector` field [S-5].
+9. `deleteByFilePaths()` removes only matching records.
+10. **Table-swap full cycle [BLOCKER-1]:**
+    - `upsertToStaging()` writes to staging table.
+    - During staging, `query()` on live table still returns old data (zero-downtime).
+    - `promoteStagingToLive()` swaps tables atomically.
+    - After promotion, `query()` returns new data.
+11. `cleanupStaging()` removes orphaned staging table without affecting live table [GAP-3].
+12. Concurrent `upsert()` calls do not corrupt the store.
+
+**Test setup:** Use a temporary directory (`os.tmpdir()`) for each test. Clean up with `fs.rm(dir, { recursive: true })` in `afterEach`.
+
+**Validation:**
+```bash
+npx vitest run src/search/__tests__/vector-store.test.ts  # → 0 failures
+```
+
+---
+
+### Task 7.2: Embedding Client — Gemini `gemini-embedding-001`
+
+---
+
+#### Step 7.2.1: Create `src/search/embedder.ts`
+
+**Pre-Condition:** `@google/generative-ai` already installed (Phase 6). Config search section defined.
+
+**Action:** Create `src/search/embedder.ts` implementing the `Embedder` class.
+
+**Class API:**
+
+```typescript
+export class Embedder {
+  constructor(config: NomosConfig['search'], logger: Logger);
+
+  /**
+   * Embed a single text string. Returns a Float32Array vector.
+   * Used for query-time embedding.
+   * Subject to request_timeout_ms [GAP-4].
+   */
+  async embedOne(text: string): Promise<Float32Array>;
+
+  /**
+   * Embed a batch of text strings. Returns Float32Array[] in the same order.
+   * Processes batches SEQUENTIALLY with rate-limit delay [TRAP-2 resolution].
+   * Each API call subject to request_timeout_ms [GAP-4].
+   * Logs rate-limit delays [S-8].
+   */
+  async embedBatch(
+    texts: string[],
+    onBatchComplete?: (batchIndex: number, totalBatches: number) => void,
+  ): Promise<Float32Array[]>;
+
+  /** Return the vector dimensions for the configured model. */
+  get dimensions(): number;
+}
+```
+
+**Internal Design:**
+
+1. **Client initialization:** `new GoogleGenerativeAI(apiKey)` where `apiKey = process.env['GEMINI_API_KEY']`. Throw `NomosError('search_api_key_missing', ...)` if not set.
+2. **Model:** `client.getGenerativeModel({ model: config.embedding_model })` → defaults to `gemini-embedding-001`.
+3. **Embedding call:** `model.embedContent(text)` for single. `model.batchEmbedContents(requests)` for batch.
+
+4. **Request timeout [GAP-4]:**
+   ```typescript
+   private async withTimeout<T>(promise: Promise<T>, label: string): Promise<T> {
+     const controller = new AbortController();
+     const timer = setTimeout(() => controller.abort(), this.config.request_timeout_ms);
+     try {
+       // Pass abort signal to the request if the SDK supports it.
+       // If not, use Promise.race as a fallback:
+       return await Promise.race([
+         promise,
+         new Promise<never>((_, reject) => {
+           controller.signal.addEventListener('abort', () => {
+             reject(new NomosError(
+               'search_embedding_failed',
+               `Embedding request timed out after ${this.config.request_timeout_ms}ms (${label})`
+             ));
+           });
+         }),
+       ]);
+     } finally {
+       clearTimeout(timer);
+     }
+   }
+   ```
+
+5. **Sequential batching with rate-limit logging [TRAP-2, S-8]:**
+   ```typescript
+   async embedBatch(texts: string[], onBatchComplete?): Promise<Float32Array[]> {
+     const results: Float32Array[] = [];
+     const batches = chunk(texts, this.config.batch_size);
+     const delayMs = Math.ceil(60_000 / this.config.embedding_requests_per_minute);
+
+     for (let i = 0; i < batches.length; i++) {
+       if (i > 0) {
+         this.logger.warn(
+           `[nomos:search:warn] Rate limiting. Waiting ${delayMs}ms before batch ${i + 1}/${batches.length}...`
+         );
+         await sleep(delayMs);
+       }
+       const batch = batches[i];
+       const vectors = await this.withTimeout(
+         this.embedBatchRaw(batch),
+         `batch ${i + 1}/${batches.length}`
+       );
+       results.push(...vectors);
+       onBatchComplete?.(i, batches.length);
+     }
+     return results;
+   }
+   ```
+   No concurrency. No `max_concurrent_requests`. One batch at a time. One config controls timing.
+
+6. **Retry:** Exponential backoff (2s, 4s, 8s) with jitter on 429/5xx errors. Max 3 retries per batch. On permanent failure, throw `NomosError('search_embedding_failed', ...)`.
+7. **Output normalization:** Gemini returns `{ embedding: { values: number[] } }`. Convert `values` to `new Float32Array(values)`.
+8. **Vector dimensions:** Configurable via `config.embedding_dimensions` (default: 768). `gemini-embedding-001` supports 768, 1536, and 3072. Pass `outputDimensionality` to the API call: `model.embedContent({ content, outputDimensionality: config.embedding_dimensions })`. Exposed via `get dimensions()` which returns `config.embedding_dimensions`.
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `rm src/search/embedder.ts`
+
+---
+
+#### Step 7.2.2: Unit test for `Embedder`
+
+**Pre-Condition:** Step 7.2.1 complete.
+
+**Action:** Create `src/search/__tests__/embedder.test.ts`.
+
+**Test cases (mocked — no real API calls):**
+1. `embedOne()` calls Gemini API with correct model and returns Float32Array.
+2. `embedBatch()` splits input into chunks of `batch_size` and processes sequentially.
+3. `embedBatch()` respects rate limit delay between batches (verify `setTimeout` calls).
+4. `embedBatch()` logs rate-limit wait message [S-8].
+5. `embedOne()` retries on 429 error with exponential backoff.
+6. `embedOne()` throws `NomosError('search_embedding_failed')` after max retries.
+7. `embedOne()` throws `NomosError('search_api_key_missing')` when GEMINI_API_KEY is unset.
+8. **Timeout [GAP-4]:** `embedOne()` throws `NomosError('search_embedding_failed', /timed out/)` when API hangs past `request_timeout_ms`.
+9. Vector dimensions match `config.embedding_dimensions` (default 768). Verify by checking `embedder.dimensions === config.embedding_dimensions` and `vector.length === config.embedding_dimensions`.
+10. `onBatchComplete` callback fires after each batch.
+
+**Mock strategy:** Mock `@google/generative-ai` module. Return predictable vectors (e.g., all-zeros with known dimensions) from mocked `embedContent` / `batchEmbedContents`. For timeout test, return a never-resolving promise.
+
+**Validation:**
+```bash
+npx vitest run src/search/__tests__/embedder.test.ts  # → 0 failures
+```
+
+---
+
+### Task 7.3: Chunk Extractor — Text Preparation
+
+---
+
+#### Step 7.3.1: Create `src/search/chunk-extractor.ts`
+
+**Pre-Condition:** Types from Step 7.0.5 defined. `ProjectMap` type available.
+
+**Action:** Create `src/search/chunk-extractor.ts` implementing the `ChunkExtractor` class.
+
+**Class API:**
+
+```typescript
+export class ChunkExtractor {
+  constructor(private readonly projectRoot: string, logger: Logger);
+
+  /**
+   * Extract file-level and symbol-level TextChunks from a ProjectMap.
+   * Uses inline semantic data from ProjectMap — no .semantic.md file reads [TRAP-5].
+   */
+  extract(map: ProjectMap): TextChunk[];
+}
+```
+
+**Internal Design:**
+
+1. **File-level chunks:** For each `FileNode` in `map.files`:
+   - **If `semantic` is non-null (inline in ProjectMap):** Compose text from `semantic.overview`, `semantic.purpose`, `semantic.key_logic[]`, `semantic.usage_context[]`. Delimit fields with labeled headers:
+     ```
+     File: {file_path}
+     Purpose: {semantic.purpose}
+     Overview: {semantic.overview}
+     Key Logic: {key_logic.join('; ')}
+     Usage Context: {usage_context.join('; ')}
+     Exports: {symbols.filter(s => s.exported).map(s => s.name).join(', ')}
+     Dependencies: {dependencies.join(', ')}
+     ```
+   - **If `semantic` is null (fallback):** Use file path, symbol names, and import sources as the text. Log a warning per file.
+   - **Chunk ID:** `file_path` (relative, e.g., `"src/services/payment.ts"`).
+
+2. **Content hash [S-6]:**
+   ```typescript
+   // Hash RAW INPUTS, not composed text.
+   // This decouples hashing from text composition logic.
+   // If composition format changes, hashes remain stable.
+   const hashInput = JSON.stringify({
+     file_path: fileNode.file_path,
+     semantic: fileNode.semantic,         // null-safe
+     symbols: fileNode.symbols.map(s => ({ name: s.name, kind: s.kind, signature: s.signature })),
+     dependencies: fileNode.dependencies,
+   });
+   const content_hash = crypto.createHash('sha256').update(hashInput).digest('hex');
+   ```
+
+3. **Symbol-level chunks:** For each `FileNode`, iterate over `symbols[]` where `exported === true` OR `kind === 'class'` OR `kind === 'function'`:
+   - Compose text:
+     ```
+     Symbol: {symbol.name} ({symbol.kind})
+     File: {file_path}
+     Signature: {symbol.signature ?? 'N/A'}
+     Lines: {symbol.line}-{symbol.end_line ?? '?'}
+     File Purpose: {semantic.purpose ?? file_path}
+     ```
+   - **Chunk ID:** `"{file_path}::{symbol.name}"`.
+   - **`parent_file_id`:** `file_path`.
+   - **`content_hash`:** Computed from raw symbol data (name, kind, signature, line, end_line) + parent file semantic hash.
+
+4. **No `.semantic.md` file reading [TRAP-5 resolution]:**
+   The original plan derived `.semantic.md` paths via fragile regex (`file_path.replace(/\.[^.]+$/, '.semantic.md')`). This breaks for:
+   - Multi-extension files (`config.test.ts` → `config.test.semantic.md` — wrong).
+   - Extensionless files (`Makefile` → unchanged path — wrong).
+
+   **Fix:** The `ProjectMap` already contains semantic data inline in `FileNode.semantic`. Use it directly. No filesystem reads for `.semantic.md`. This eliminates the path derivation problem entirely.
+
+5. **Empty text guard:** Skip chunks where composed text is shorter than 20 characters.
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `rm src/search/chunk-extractor.ts`
+
+---
+
+#### Step 7.3.2: Unit test for `ChunkExtractor`
+
+**Pre-Condition:** Step 7.3.1 complete.
+
+**Action:** Create `src/search/__tests__/chunk-extractor.test.ts`.
+
+**Test cases:**
+1. File with `semantic` data produces a file-level chunk with all fields concatenated.
+2. File without `semantic` data produces a fallback chunk with file path and symbol names.
+3. Exported symbols produce symbol-level chunks.
+4. Non-exported, non-class, non-function symbols are skipped.
+5. Chunk IDs are correct: file path for file-level, `file::symbol` for symbol-level.
+6. `parent_file_id` on symbol chunks points to parent file.
+7. Chunks shorter than 20 chars are skipped.
+8. `content_hash` is deterministic (same input → same hash) [S-6].
+9. `content_hash` does NOT change when text composition format changes (only when raw inputs change) [S-6].
+10. No filesystem reads for `.semantic.md` files [TRAP-5].
+
+**Test setup:** Create a minimal `ProjectMap` object in-memory with 2–3 `FileNode` entries (one with semantic, one without, one with symbols).
+
+**Validation:**
+```bash
+npx vitest run src/search/__tests__/chunk-extractor.test.ts  # → 0 failures
+```
+
+---
+
+### Task 7.4: Indexing Pipeline — Extract → Embed → Upsert (Streaming + Table-Swap)
+
+---
+
+#### Step 7.4.1: Create `src/search/indexer.ts`
+
+**Pre-Condition:** Tasks 7.1–7.3 complete. All sub-modules functional.
+
+**Action:** Create `src/search/indexer.ts` implementing the `SearchIndexer` class.
+
+**Class API:**
+
+```typescript
+export class SearchIndexer {
+  constructor(
+    projectRoot: string,
+    config: NomosConfig,
+    logger: Logger,
+  );
+
+  /**
+   * Full index: extract all chunks, embed in streaming batches, upsert to staging,
+   * then atomic table-swap to live [BLOCKER-1].
+   * Writes metadata with status tracking [BLOCKER-2].
+   * Returns IndexMetadata.
+   */
+  async fullIndex(cancellationFlag?: { cancelled: boolean }): Promise<IndexMetadata>;
+
+  /**
+   * Incremental index: validates dimensions [BLOCKER-3], re-indexes changed + failed files [GAP-1].
+   * Returns updated IndexMetadata.
+   */
+  async incrementalIndex(cancellationFlag?: { cancelled: boolean }): Promise<IndexMetadata>;
+
+  /**
+   * Dry-run: extract and count chunks without embedding or writing [S-2].
+   * Returns chunk count summary.
+   */
+  async dryRun(): Promise<{ fileChunks: number; symbolChunks: number; totalChunks: number }>;
+}
+```
+
+**Internal Design — Full Index Flow [BLOCKER-1, BLOCKER-2, BLOCKER-4]:**
+
+```
+1. Load project_map.json from config.graph.output_dir
+   └─ If not found: throw NomosError('search_index_failed', 'project_map.json not found. Run: arc map')
+
+2. Write IndexMetadata with status: "in_progress" [BLOCKER-2]
+   └─ This marks the index as incomplete BEFORE any mutation occurs.
+   └─ If process crashes after this point, next startup detects "in_progress" → forces full re-index.
+
+3. ChunkExtractor.extract(projectMap) → TextChunk[]
+   └─ Log: "[nomos:search:info] Extracted {N} chunks ({F} file-level, {S} symbol-level)"
+
+4. VectorStore.cleanupStaging() → remove orphaned staging table from prior crash [GAP-3]
+
+5. STREAMING BATCH LOOP [BLOCKER-4]:
+   └─ Split TextChunk[] into batches of config.batch_size
+   └─ For each batch:
+       a. Check cancellationFlag — if cancelled, goto step 7 (partial completion)
+       b. Embedder.embedBatch(batch.map(c => c.text)) → Float32Array[]
+          └─ On batch failure: log error, record file_paths in failedFiles[], continue [GAP-1]
+       c. Compose VectorRecord[] for THIS BATCH ONLY
+          └─ graph_depth: from projectMap.files[file_path].depth
+          └─ dependents_count: from projectMap.files[file_path].dependents.length
+          └─ last_indexed: new Date().toISOString()
+       d. VectorStore.upsertToStaging(batchRecords) → immediate write, release references
+       e. Log: "[nomos:search:info] Embedded batch {i}/{total} ({N} chunks)"
+
+6. VectorStore.promoteStagingToLive() [BLOCKER-1]
+   └─ Atomic swap: staging table becomes live table.
+   └─ If this fails: live table still contains OLD data (safe). Throw error.
+
+7. Write IndexMetadata with status: "complete" [BLOCKER-2]
+   └─ Includes: total counts, per-file hashes, embedding_model, vector_dimensions, failed_files
+   └─ Atomic write: write to .tmp file, then rename.
+   └─ If cancelled in step 5: write with status: "in_progress" + partial counts + failed_files.
+     (Next run detects "in_progress" → forces full re-index.)
+
+8. Return IndexMetadata
+```
+
+**Internal Design — Incremental Index Flow [BLOCKER-3, GAP-1]:**
+
+```
+1. Load project_map.json
+
+2. Load existing IndexMetadata from {vector_store_path}/index-meta.json
+   └─ If not found: fall back to fullIndex()
+   └─ If status === "in_progress": fall back to fullIndex() [BLOCKER-2]
+       Log: "[nomos:search:warn] Previous index incomplete. Running full re-index."
+
+3. DIMENSION VALIDATION [BLOCKER-3]:
+   └─ Compare IndexMetadata.embedding_model against config.search.embedding_model
+   └─ Compare IndexMetadata.vector_dimensions against config.search.embedding_dimensions
+   └─ If EITHER mismatches:
+       Log: "[nomos:search:warn] Embedding model/dimensions changed ({old} → {new}). Forcing full re-index."
+       Fall back to fullIndex()
+
+4. ChunkExtractor.extract(projectMap) → TextChunk[]
+
+5. Compute diff:
+   └─ changed = chunks where content_hash differs from IndexMetadata.files[file_path].content_hash
+   └─ new_files = chunks whose file_path is not in IndexMetadata.files
+   └─ removed = files in IndexMetadata.files but not in projectMap
+   └─ failed_retry = chunks whose file_path is in IndexMetadata.failed_files [GAP-1]
+   └─ to_reindex = union(changed, new_files, failed_retry)
+
+6. If to_reindex is empty AND removed is empty:
+   └─ Log: "[nomos:search:info] Index is up-to-date. No changes detected."
+   └─ Return existing IndexMetadata unchanged.
+
+7. Write IndexMetadata with status: "in_progress" [BLOCKER-2]
+
+8. VectorStore.deleteByFilePaths([...removed, ...to_reindex.map(c => c.file_path)])
+
+9. STREAMING BATCH LOOP for to_reindex [BLOCKER-4]:
+   └─ (Same pattern as full index step 5 — embed batch, compose records, upsert immediately)
+
+10. Update IndexMetadata:
+    └─ status: "complete"
+    └─ Update per-file entries for changed/new files
+    └─ Remove entries for removed files
+    └─ Clear failed_files for successfully re-embedded files; keep any that failed again [GAP-1]
+    └─ Update last_incremental_index, total counts
+
+11. Write IndexMetadata (atomic: .tmp then rename) [BLOCKER-2]
+
+12. Return IndexMetadata
+```
+
+**Cancellation safety [GAP-3]:**
+- The cancellation flag is checked at the TOP of each batch iteration (step 5a / 9).
+- On cancellation during full index: staging table is orphaned (harmless). Live table untouched. Metadata written as `"in_progress"`. Next run cleans up staging and forces full re-index.
+- On cancellation during incremental index: partial upserts are durable in the live table (LanceDB transactional writes). Metadata written as `"in_progress"`. Next run forces full re-index.
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `rm src/search/indexer.ts`
+
+---
+
+#### Step 7.4.2: Unit test for `SearchIndexer`
+
+**Pre-Condition:** Step 7.4.1 complete.
+
+**Action:** Create `src/search/__tests__/indexer.test.ts`.
+
+**Test cases (mocked Embedder, real VectorStore with temp dir):**
+1. `fullIndex()` loads project map, extracts chunks, embeds, upserts via staging, swaps, writes metadata.
+2. `fullIndex()` uses table-swap (staging → live) NOT `reset()` + `upsert()` [BLOCKER-1].
+3. `fullIndex()` writes `status: "in_progress"` BEFORE embedding, `status: "complete"` AFTER [BLOCKER-2].
+4. `fullIndex()` upserts per-batch, not all-at-once [BLOCKER-4].
+5. `incrementalIndex()` only re-embeds changed files (verify by checking `embedBatch` call count).
+6. `incrementalIndex()` re-embeds files in `failed_files` even if hash unchanged [GAP-1].
+7. `incrementalIndex()` deletes records for removed files.
+8. `incrementalIndex()` falls back to `fullIndex()` when no metadata exists.
+9. `incrementalIndex()` falls back to `fullIndex()` when `status === "in_progress"` [BLOCKER-2].
+10. `incrementalIndex()` falls back to `fullIndex()` on embedding model mismatch [BLOCKER-3].
+11. `incrementalIndex()` falls back to `fullIndex()` on vector dimension mismatch [BLOCKER-3].
+12. Index metadata file is written with correct totals, per-file hashes, and `failed_files`.
+13. Cancellation flag stops processing between batches; metadata written as `"in_progress"`.
+14. Missing `project_map.json` throws `NomosError('search_index_failed')`.
+15. Partial embedding failure: failed files recorded in `IndexMetadata.failed_files` [GAP-1], remaining files indexed successfully.
+16. `dryRun()` returns chunk counts without calling Embedder or VectorStore [S-2].
+
+**Validation:**
+```bash
+npx vitest run src/search/__tests__/indexer.test.ts  # → 0 failures
+```
+
+---
+
+### Task 7.5: Query Engine — Search Flow
+
+---
+
+#### Step 7.5.1: Create `src/search/graph-enricher.ts`
+
+**Pre-Condition:** `ProjectMap` type available.
+
+**Action:** Create `src/search/graph-enricher.ts` implementing the `GraphEnricher` class.
+
+**Class API:**
+
+```typescript
+export class GraphEnricher {
+  private projectMap: ProjectMap | null = null;
+
+  constructor(
+    private readonly projectMapPath: string,
+    private readonly logger: Logger,
+  );
+
+  /**
+   * Lazy-load and cache project_map.json [GAP-5].
+   * Parsed once per instance lifetime. Subsequent calls return cached data.
+   */
+  private async loadMap(): Promise<ProjectMap>;
+
+  /**
+   * Enrich raw search results with dependency graph metadata.
+   * Stale results (file deleted since index) get is_stale = true [TRAP-4].
+   */
+  async enrich(results: RawSearchResult[]): Promise<SearchResult[]>;
+}
+
+interface RawSearchResult {
+  id: string;
+  type: ChunkType;
+  file_path: string;
+  symbol_name: string | null;
+  symbol_type: string | null;
+  line_start: number | null;
+  line_end: number | null;
+  purpose: string;
+  similarity_score: number;
+}
+```
+
+**Internal Design:**
+
+1. **Lazy loading [GAP-5]:**
+   ```typescript
+   private async loadMap(): Promise<ProjectMap> {
+     if (this.projectMap) return this.projectMap;
+     const raw = await fs.readFile(this.projectMapPath, 'utf-8');
+     this.projectMap = JSON.parse(raw);
+     return this.projectMap;
+   }
+   ```
+   For CLI usage (one search per process), the map is loaded once. No repeated 20MB parses.
+
+2. For each result, look up `projectMap.files[result.file_path]`.
+3. If found: set `graph_depth`, `dependents_count`, `is_core_module`, `is_stale = false`.
+4. **If NOT found [TRAP-4]:** set `graph_depth = -1`, `dependents_count = 0`, `is_core_module = false`, `is_stale = true`. The `-1` sentinel is an internal value — it NEVER reaches CLI output directly. The `is_stale` boolean is the public signal.
+5. Sort results by `similarity_score` descending (preserve embedding rank).
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `rm src/search/graph-enricher.ts`
+
+---
+
+#### Step 7.5.2: Create `src/search/query-engine.ts`
+
+**Pre-Condition:** Steps 7.1.1, 7.2.1, 7.5.1 complete.
+
+**Action:** Create `src/search/query-engine.ts` implementing the `QueryEngine` class.
+
+**Class API:**
+
+```typescript
+export class QueryEngine {
+  constructor(
+    projectRoot: string,
+    config: NomosConfig,
+    logger: Logger,
+  );
+
+  /**
+   * Execute a semantic search query.
+   * Pipeline: embed query → vector search → graph enrich → deduplicate → rank → return.
+   */
+  async search(query: string, options?: {
+    topK?: number;
+    threshold?: number;
+  }): Promise<SearchResult[]>;
+}
+```
+
+**Internal Design:**
+
+```
+1. Validate: query string must be non-empty after trim.
+   └─ Throw NomosError('search_query_failed', 'Query must be a non-empty string.') otherwise.
+
+2. Check vector index exists:
+   └─ Read {vector_store_path}/index-meta.json
+   └─ If not found: throw NomosError('search_index_not_found', 'No index found. Run: arc index')
+   └─ If status === "in_progress": log warning "Index is incomplete. Results may be partial."
+
+3. Initialize VectorStore [GAP-2]:
+   └─ VectorStore.init() — wrapped in try-catch that produces actionable error.
+
+4. Embed query:
+   └─ Embedder.embedOne(query.trim()) → Float32Array
+   └─ Subject to request_timeout_ms [GAP-4]
+
+5. Vector search:
+   └─ VectorStore.query(queryVector, topK, threshold) → results with similarity_score
+   └─ similarity_score already ∈ [0, 1] — conversion done in VectorStore [S-3]
+
+6. Graph enrich:
+   └─ GraphEnricher.enrich(rawResults) → SearchResult[]
+   └─ project_map.json loaded lazily and cached [GAP-5]
+
+7. De-duplicate [TRAP-3 — DETERMINISTIC RULE]:
+   └─ Group results by file_path.
+   └─ For each file_path that has BOTH a 'file' type result AND one or more 'symbol' type results:
+       a. Compute score gap = abs(file_result.similarity_score - max(symbol_results.similarity_score))
+       b. If score gap <= 0.05: REMOVE the file-level result. Keep only symbol results.
+       c. If score gap > 0.05: keep both (they are sufficiently distinct in relevance).
+   └─ This is a hard rule. "Remove" means filter out of the result array entirely.
+
+8. Sort by similarity_score descending.
+
+9. Return top-K SearchResult[]
+```
+
+**Stale index warning:** If `index-meta.json` `last_full_index` is older than `project_map.json` `generated_at`, log: `"[nomos:search:warn] Index is older than project map. Consider running: arc index --incremental"`.
+
+**Validation:**
+```bash
+npx tsc --noEmit  # → exit code 0
+```
+
+**Rollback:** `rm src/search/query-engine.ts`
+
+---
+
+#### Step 7.5.3: Unit tests for `GraphEnricher` and `QueryEngine`
+
+**Pre-Condition:** Steps 7.5.1–7.5.2 complete.
+
+**Action:** Create:
+- `src/search/__tests__/graph-enricher.test.ts`
+- `src/search/__tests__/query-engine.test.ts`
+
+**GraphEnricher test cases:**
+1. Results are enriched with correct `graph_depth` and `dependents_count` from project map.
+2. Core modules are correctly flagged (`is_core_module = true`).
+3. Missing file in project map sets `is_stale = true` and `graph_depth = -1` [TRAP-4].
+4. Results maintain similarity_score ranking after enrichment.
+5. `loadMap()` is called only once across multiple `enrich()` calls (caching) [GAP-5].
+
+**QueryEngine test cases (mocked Embedder + VectorStore):**
+1. `search()` embeds query, queries store, enriches, and returns ranked results.
+2. `search()` throws `NomosError('search_index_not_found')` when no index exists.
+3. `search()` throws `NomosError('search_query_failed')` on empty query string.
+4. `search()` respects `topK` and `threshold` overrides.
+5. Stale index warning is logged when index is older than project map.
+6. **De-duplication [TRAP-3]:** symbol-level result within 0.05 of parent file-level result → file-level result removed.
+7. **De-duplication [TRAP-3]:** symbol-level result MORE than 0.05 from parent file-level result → both kept.
+8. `search()` wraps VectorStore.init() failure with actionable error message [GAP-2].
+
+**Validation:**
+```bash
+npx vitest run src/search/__tests__/graph-enricher.test.ts  # → 0 failures
+npx vitest run src/search/__tests__/query-engine.test.ts    # → 0 failures
+```
+
+---
+
+### Task 7.6: CLI Commands — `arc index` and `arc search`
+
+---
+
+#### Step 7.6.1: Create `src/commands/index.ts`
+
+**Pre-Condition:** Task 7.4 complete. `SearchIndexer` functional.
+
+**Action:** Create `src/commands/index.ts` following the existing command registration pattern.
+
+**Command signature:**
+```
+arc index [--incremental] [--force] [--dry-run]
+```
+
+| Flag | Behavior |
+|---|---|
+| (no flags) | Full re-index. Table-swap strategy. |
+| `--incremental` | Only re-index changed + failed files (content hash + failed_files comparison). |
+| `--force` | Force full re-index even if incremental metadata exists. Same as no flags. |
+| `--dry-run` | Extract and count chunks without embedding or writing [S-2]. No API calls. No cost. |
+
+**Implementation:**
+
+```typescript
+export function registerIndexCommand(program: Command): void {
+  program
+    .command('index')
+    .description('Build or rebuild the vector search index from project map')
+    .option('--incremental', 'Only re-index files changed since last indexing run')
+    .option('--force', 'Force full re-index (ignore incremental metadata)')
+    .option('--dry-run', 'Count chunks without embedding (no API calls, no writes)')
+    .action(async (opts: { incremental?: boolean; force?: boolean; dryRun?: boolean }) => {
+      // 1. loadConfig()
+      // 2. Create logger
+      // 3. Create SearchIndexer
+      // 4. If --dry-run: call dryRun(), print summary, exit 0
+      // 5. Register SIGINT handler:
+      //    - Set cancellationFlag.cancelled = true
+      //    - Log: "[nomos:search:warn] SIGINT received. Finishing current batch..."
+      //    - The indexer will write partial metadata and exit cleanly.
+      // 6. Call fullIndex() or incrementalIndex() based on flags
+      // 7. Print summary:
+      //    "Indexed {total_chunks} chunks ({files} files, {symbols} symbols) in {duration}s"
+      //    "Vector index stored at: {vector_store_path}"
+      //    If failed_files.length > 0:
+      //      "⚠ {N} files failed embedding. They will be retried on next incremental index."
+      // 8. Exit 0 on success, 1 on fatal error
+    });
+}
+```
+
+**Progress output:** Print to stderr (not stdout — preserves machine-parseability):
+```
+[nomos:search:info] Extracting chunks from project map...
+[nomos:search:info] Extracted 342 chunks (142 file-level, 200 symbol-level)
+[nomos:search:info] Embedding batch 1/7 (50 chunks)...
+[nomos:search:warn] Rate limiting. Waiting 200ms before batch 2/7...
+[nomos:search:info] Embedding batch 2/7 (50 chunks)...
+...
+[nomos:search:info] Writing to staging table...
+[nomos:search:info] Promoting staging to live (atomic swap)...
+[nomos:search:info] Writing index metadata...
+```
+
+**Dry-run output [S-2]:**
+```
+[nomos:search:info] DRY RUN — no API calls, no writes.
+[nomos:search:info] Would index: 342 chunks (142 file-level, 200 symbol-level)
+[nomos:search:info] Estimated API calls: 7 batches × 50 chunks
+```
+
+**Validation:**
+```bash
+npx tsc --noEmit                                    # → exit code 0
+npm run build && node dist/cli.js index --help      # → shows --incremental, --force, --dry-run
+```
+
+**Rollback:** `rm src/commands/index.ts`
+
+---
+
+#### Step 7.6.2: Create `src/commands/search.ts`
+
+**Pre-Condition:** Task 7.5 complete. `QueryEngine` functional.
+
+**Action:** Create `src/commands/search.ts` following the existing command registration pattern.
+
+**Command signature:**
+```
+arc search <query> [--top <N>] [--threshold <score>] [--json]
+```
+
+| Flag | Default | Behavior |
+|---|---|---|
+| `<query>` | (required) | Natural language search query |
+| `--top <N>` | 5 | Maximum number of results |
+| `--threshold <score>` | 0.7 | Minimum similarity score (0.0–1.0) |
+| `--json` | false | Output raw JSON instead of formatted table |
+
+**Human-readable output format:**
+
+```
+Results for: "how is refund handled?"
+
+  1. src/services/payment.ts :: processRefund()    [0.96]  L45-82
+     "Processes a refund request via Stripe, validates eligibility, updates order state"
+     ⚠ Core Module (depth 5) — modifying this affects 10 dependents
+
+  2. src/services/payment.ts                       [0.91]
+     "Handles payment processing and refund logic"
+     ⚠ Core Module (depth 5) — modifying this affects 10 dependents
+
+  3. src/middleware/billing.ts                      [0.84]
+     "Validates billing state before checkout"
+     Leaf Module (depth 1) — 2 dependents
+
+Found 3 results (threshold: 0.70, top: 5)
+```
+
+**Stale result formatting [TRAP-4]:**
+```
+  4. src/legacy/old-handler.ts                     [0.78]
+     "Legacy request handler for v1 API"
+     ⚠ Stale — file removed since last index. Run: arc index --incremental
+```
+When `is_stale === true`: do NOT print `depth -1` or any numeric depth. Print the stale warning message. No negative numbers in CLI output.
+
+**JSON output format (`--json`) [S-5]:**
+```json
+{
+  "query": "how is refund handled?",
+  "results": [
+    {
+      "id": "src/services/payment.ts::processRefund",
+      "type": "symbol",
+      "file_path": "src/services/payment.ts",
+      "symbol_name": "processRefund",
+      "symbol_type": "function",
+      "line_start": 45,
+      "line_end": 82,
+      "purpose": "Processes a refund request via Stripe...",
+      "similarity_score": 0.96,
+      "graph_depth": 5,
+      "dependents_count": 10,
+      "is_core_module": true,
+      "is_stale": false
+    }
+  ],
+  "metadata": {
+    "top_k": 5,
+    "threshold": 0.7,
+    "total_results": 3,
+    "index_age": "2026-04-06T12:00:00Z"
+  }
+}
+```
+
+**Verify:** `JSON.stringify(result)` must NOT contain a `vector` field. The `SearchResult` type excludes it by design [S-5].
+
+Print JSON to stdout. Print nothing to stderr in `--json` mode (machine-parseable output).
+
+**Edge cases:**
+- No results found: Print `"No results found above threshold {threshold}."` Exit 0.
+- Index not found: Print error message, suggest `arc index`. Exit 1.
+- Index status `in_progress`: Print warning, proceed with partial search. Exit 0.
+- Empty query string: Print usage help. Exit 1.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                              # → exit code 0
+npm run build && node dist/cli.js search --help               # → shows options
+```
+
+**Rollback:** `rm src/commands/search.ts`
+
+---
+
+#### Step 7.6.3: Register commands in `src/cli.ts`
+
+**Pre-Condition:** Steps 7.6.1–7.6.2 complete.
+
+**Action:**
+
+1. Add imports at the top of `src/cli.ts`:
+```typescript
+import { registerIndexCommand } from './commands/index.js';
+import { registerSearchCommand } from './commands/search.js';
+```
+
+2. Add to the registration array (in the same position pattern as existing commands):
+```typescript
+registerIndexCommand,
+registerSearchCommand,
+```
+
+**Validation:**
+```bash
+npx tsc --noEmit                        # → exit code 0
+npm run build                           # → exit code 0
+node dist/cli.js --help                 # → shows 'index' and 'search' commands
+node dist/cli.js index --help           # → shows --incremental, --force, --dry-run
+node dist/cli.js search --help          # → shows <query>, --top, --threshold, --json
+```
+
+**Rollback:** `git checkout src/cli.ts`
+
+---
+
+### Task 7.7: Integration Testing & End-to-End Verification
+
+---
+
+#### Step 7.7.1: Integration tests — Full pipeline + CI-compatible mock
+
+**Pre-Condition:** All previous tasks complete. `project_map.json` exists with enriched data.
+
+**Action:** Create `src/search/__tests__/integration.test.ts`.
+
+**Test A — Live API (requires GEMINI_API_KEY — skip in CI if unset):**
+
+1. **Setup:** Copy a minimal `project_map.json` fixture (5 files, ~15 symbols) to a temp directory.
+2. **Full index:**
+   - Create `SearchIndexer` with temp directory config.
+   - Call `fullIndex()`.
+   - Assert: `IndexMetadata.status === "complete"` [BLOCKER-2].
+   - Assert: `IndexMetadata.total_files_indexed === 5`.
+   - Assert: `IndexMetadata.total_chunks > 5` (file + symbol chunks).
+   - Assert: `IndexMetadata.embedding_model === 'gemini-embedding-001'` [BLOCKER-3].
+   - Assert: `IndexMetadata.vector_dimensions === config.search.embedding_dimensions` [BLOCKER-3].
+   - Assert: `IndexMetadata.failed_files.length === 0` [GAP-1].
+   - Assert: Vector store `count() > 0`.
+   - Assert: `index-meta.json` file exists.
+3. **Search:**
+   - Create `QueryEngine`.
+   - Call `search("error handling and retry logic")`.
+   - Assert: results.length > 0.
+   - Assert: each result has `similarity_score >= 0.7` and `similarity_score <= 1.0` [S-3].
+   - Assert: no result has a `vector` field [S-5].
+   - Assert: each result has valid `file_path`, `graph_depth`, `dependents_count`.
+   - Assert: stale results (if any) have `is_stale === true` [TRAP-4].
+4. **Incremental re-index:**
+   - Modify one file's semantic data in the fixture map.
+   - Call `incrementalIndex()`.
+   - Assert: only 1 file re-embedded (check embed call count via spy).
+   - Assert: metadata `status === "complete"`.
+5. **Cleanup:** Remove temp directory.
+
+**Guard:** `describe.skipIf(!process.env['GEMINI_API_KEY'])` — skipped if API key absent.
+
+**Test B — Mock-embedder integration (runs in CI always) [S-4]:**
+
+1. **Setup:** Same fixture. Create a `MockEmbedder` that returns deterministic vectors matching `config.embedding_dimensions` (e.g., hash-based: SHA-256 of text → repeated to fill `config.embedding_dimensions` floats as Float32Array).
+2. **Full index with mock embedder.**
+3. **Search with mock embedder.**
+4. Assert: pipeline completes end-to-end. Results are ranked. Metadata is valid.
+5. Assert: table-swap occurred (staging table does not exist after completion) [BLOCKER-1].
+6. Assert: de-duplication rule applied correctly [TRAP-3].
+
+This test runs without `GEMINI_API_KEY` — it exercises the full pipeline minus the actual API call.
+
+**Validation:**
+```bash
+# CI-compatible (always runs):
+npx vitest run src/search/__tests__/integration.test.ts --grep "mock-embedder"
+
+# Full integration (requires API key):
+GEMINI_API_KEY=$GEMINI_API_KEY npx vitest run src/search/__tests__/integration.test.ts
+```
+
+---
+
+#### Step 7.7.2: End-to-end CLI verification
+
+**Pre-Condition:** Step 7.7.1 passes. Project is built.
+
+**Action:** Manual CLI verification sequence:
+
+```bash
+# 1. Build
+npm run build
+
+# 2. Ensure project map exists
+node dist/cli.js map --no-ai  # Quick structural map (no API calls)
+
+# 3. Dry run (no API calls, no cost) [S-2]
+node dist/cli.js index --dry-run
+# Expected: "Would index: {N} chunks ({F} file-level, {S} symbol-level)"
+# Expected: exit code 0
+
+# 4. Full index
+node dist/cli.js index
+# Expected: "Indexed {N} chunks ({F} files, {S} symbols) in {T}s"
+# Expected: exit code 0
+
+# 5. Verify metadata
+cat tasks-management/graph/vector_index/index-meta.json | node -e "
+  let d=''; process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const m=JSON.parse(d);
+    console.log('status:', m.status);                // → 'complete'
+    console.log('model:', m.embedding_model);        // → 'gemini-embedding-001'
+    console.log('dims:', m.vector_dimensions);       // → matches config.embedding_dimensions
+    console.log('failed:', m.failed_files.length);   // → 0
+  });
+"
+
+# 6. Search — natural language
+node dist/cli.js search "error handling"
+# Expected: ranked results with file paths, scores, and dependency info
+# Expected: no results with "depth -1" in output [TRAP-4]
+
+# 7. Search — JSON output [S-5]
+node dist/cli.js search "configuration loading" --json | node -e "
+  let d=''; process.stdin.on('data',c=>d+=c);
+  process.stdin.on('end',()=>{
+    const j=JSON.parse(d);
+    console.log('results:', j.results.length);
+    console.log('has vector field:', j.results.some(r => 'vector' in r));  // → false
+    console.log('valid JSON: true');
+  });
+"
+# Expected: "has vector field: false"
+
+# 8. Search — threshold and top-K
+node dist/cli.js search "state management" --top 3 --threshold 0.8
+# Expected: at most 3 results, all with score >= 0.80
+
+# 9. Incremental index
+node dist/cli.js index --incremental
+# Expected: "Index is up-to-date. No changes detected." (if nothing changed)
+
+# 10. Stale index detection
+# Modify a file, re-run arc map, then arc search
+# Expected: "[nomos:search:warn] Index is older than project map..."
+
+# 11. Missing index error
+rm -rf tasks-management/graph/vector_index
+node dist/cli.js search "anything"
+# Expected: error message suggesting "arc index"
+# Expected: exit code 1
+
+# 12. Type check and full test suite
+npx tsc --noEmit           # → exit code 0
+npx vitest run             # → 0 failures (all existing + new tests)
+```
+
+---
+
+#### Step 7.7.3: Verify cosine similarity correctness
+
+**Pre-Condition:** Vector store operational.
+
+**Action:** Create `src/search/__tests__/similarity.test.ts`:
+
+```typescript
+test('similar texts produce similarity > 0.8', async () => {
+  const embedder = new Embedder(config, logger);
+  const v1 = await embedder.embedOne('process payment refund');
+  const v2 = await embedder.embedOne('handle refund for customer payment');
+  const similarity = cosineSimilarity(v1, v2);
+  expect(similarity).toBeGreaterThan(0.8);
+});
+
+test('unrelated texts produce similarity < 0.5', async () => {
+  const embedder = new Embedder(config, logger);
+  const v1 = await embedder.embedOne('process payment refund');
+  const v2 = await embedder.embedOne('configure webpack build optimization');
+  const similarity = cosineSimilarity(v1, v2);
+  expect(similarity).toBeLessThan(0.5);
+});
+
+test('similarity is always in [0, 1]', async () => {
+  const embedder = new Embedder(config, logger);
+  const v1 = await embedder.embedOne('any arbitrary text');
+  const v2 = await embedder.embedOne('completely different content');
+  const similarity = cosineSimilarity(v1, v2);
+  expect(similarity).toBeGreaterThanOrEqual(0);
+  expect(similarity).toBeLessThanOrEqual(1);
+});
+
+function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+```
+
+**Guard:** `describe.skipIf(!process.env['GEMINI_API_KEY'])`.
+
+**Validation:**
+```bash
+GEMINI_API_KEY=$GEMINI_API_KEY npx vitest run src/search/__tests__/similarity.test.ts
+```
+
+---
+
+## 3. Final Acceptance Checklist
+
+Every check must pass. Failure on any = investigation required.
+
+| # | Criterion | Verification | Addresses |
+|---|-----------|-------------|-----------|
+| AC-1 | `arc index` builds vector index from project map | `node dist/cli.js index` → exit 0, index files created | Core |
+| AC-2 | File-level AND symbol-level embeddings generated | `index-meta.json` shows `total_symbols_indexed > 0` | Core |
+| AC-3 | `arc index --incremental` only re-indexes changed files | Modify 1 file, re-map, re-index: only 1 file re-embedded | Core |
+| AC-4 | `arc search` returns semantically relevant results | Search for concept not in any symbol name → gets relevant results | Core |
+| AC-5 | Symbol-level results include line range | Result includes `L{start}-{end}` for symbol chunks | Core |
+| AC-6 | Dependency-aware enrichment present | Results show `graph_depth`, `dependents_count`, core/leaf label | Core |
+| AC-7 | JSON output valid and vector-free | `--json` output parses; no `vector` field in results | S-5 |
+| AC-8 | Threshold filtering works | `--threshold 0.99` returns fewer results than `--threshold 0.5` | Core |
+| AC-9 | Top-K limiting works | `--top 1` returns exactly 1 result (if any match) | Core |
+| AC-10 | Missing index → clear error | `arc search` without index → error, suggests `arc index` | Core |
+| AC-11 | Missing API key → clear error | `arc index` without GEMINI_API_KEY → clear error message | Core |
+| AC-12 | No regressions | `npx vitest run` → 0 failures across entire test suite | Core |
+| AC-13 | Type safety | `npx tsc --noEmit` → exit 0 | Core |
+| AC-14 | Build succeeds | `npm run build` → exit 0, `node dist/cli.js --help` shows all commands | Core |
+| AC-15 | Search < 2s for 500 indexed files | `time arc search "query"` on indexed project | GAP-5 |
+| AC-16 | Full re-index is zero-downtime | During `arc index`, concurrent `arc search` returns old results (not empty/error) | BLOCKER-1 |
+| AC-17 | Crash recovery works | Kill indexer mid-run; next `arc index --incremental` detects `"in_progress"` → full re-index | BLOCKER-2 |
+| AC-18 | Model change triggers full re-index | Change `embedding_model` in config; `--incremental` falls back to full | BLOCKER-3 |
+| AC-19 | Failed files retried on incremental | Simulate embedding failure; next `--incremental` re-embeds failed files | GAP-1 |
+| AC-20 | API timeout handled | Mock hanging API; indexer throws after `request_timeout_ms` | GAP-4 |
+| AC-21 | De-duplication deterministic | Symbol + parent file within 0.05 → file-level result removed | TRAP-3 |
+| AC-22 | Stale results formatted correctly | Deleted file in results → shows stale warning, no `depth -1` | TRAP-4 |
+| AC-23 | Dry-run makes no API calls | `arc index --dry-run` → chunk count printed, no embeddings, no writes | S-2 |
+| AC-24 | CI integration test passes | Mock-embedder integration test runs without API key | S-4 |
+| AC-25 | LanceDB pinned to exact version | `package.json` shows `"0.14.3"` not `"^0.14.3"` | M-9 |
+
+---
+
+## 4. Dependency Graph (Execution Order)
+
+```
+7.0.1 ─── 7.0.2 ─┐
+                  │
+7.0.3 ────────────┤
+                  │
+7.0.4 ─── 7.0.5 ─┤
+                  │
+7.0.6 ────────────┘
+                  │
+        ┌─────────┼──────────┐
+        ▼         ▼          ▼
+      7.1.1     7.2.1      7.3.1
+        │         │          │
+      7.1.2     7.2.2      7.3.2
+        │         │          │
+        └─────────┼──────────┘
+                  │
+                7.4.1
+                  │
+                7.4.2
+                  │
+          ┌───────┴───────┐
+          ▼               ▼
+        7.5.1           7.5.2
+          │               │
+          └───────┬───────┘
+                  │
+                7.5.3
+                  │
+          ┌───────┼───────┐
+          ▼       ▼       ▼
+        7.6.1   7.6.2   7.6.3
+          │       │       │
+          └───────┼───────┘
+                  │
+          ┌───────┼───────┐
+          ▼       ▼       ▼
+        7.7.1   7.7.2   7.7.3
+```
+
+**Parallelizable:** Tasks 7.1, 7.2, and 7.3 can be implemented in parallel after Task 7.0 completes. Tasks 7.6.1, 7.6.2, and 7.6.3 can be implemented in parallel after Task 7.5.
+
+---
+
+## 5. Risk Register (Updated)
+
+| Risk | Probability | Impact | Mitigation | Status |
+|---|---|---|---|---|
+| LanceDB native binding fails in esbuild bundle | Medium | Blocker | `--external` in esbuild. Post-build verification. | Mitigated |
+| Gemini rate limits during large index | High | Delays | Sequential batching, `embedding_requests_per_minute`, backoff. No dead config. | Mitigated (TRAP-2) |
+| LanceDB API breaking changes (pre-1.0) | Low | Medium | **Pinned to exact `0.14.3`** (M-9). Test suite catches regressions. | Mitigated |
+| Vector dimensions mismatch on model change | Low | Data corruption | **Dimension validation in incremental flow** (BLOCKER-3). Auto-triggers full re-index. | Mitigated |
+| Large projects exceed memory during embedding | Medium | Crash | **Streaming batch upsert** (BLOCKER-4). Records written and released per-batch. | Mitigated |
+| `.semantic.md` files missing or path derivation fails | High | Degraded quality | **Uses inline `ProjectMap.semantic` data** (TRAP-5). No filesystem reads for .semantic.md. | Mitigated |
+| Process crash during full re-index | Medium | Data loss | **Table-swap** (BLOCKER-1) + **status field** (BLOCKER-2). Old index preserved during crash. | Mitigated |
+| Partial embedding failure → permanent blind spots | Medium | Search gaps | **`failed_files[]`** in metadata (GAP-1). Re-indexed on next incremental run. | Mitigated |
+| API hangs indefinitely | Low | CLI freeze | **30s AbortController timeout** (GAP-4) on every API call. | Mitigated |
+| SIGINT during indexing | Medium | Corruption | **Table-swap** eliminates danger zone. SIGINT leaves old index intact. | Mitigated (GAP-3) |
+
+---
+
+## 6. File Inventory
+
+**New files (15):**
+```
+src/search/vector-store.ts
+src/search/embedder.ts
+src/search/chunk-extractor.ts
+src/search/indexer.ts
+src/search/query-engine.ts
+src/search/graph-enricher.ts
+src/search/__tests__/vector-store.test.ts
+src/search/__tests__/embedder.test.ts
+src/search/__tests__/chunk-extractor.test.ts
+src/search/__tests__/indexer.test.ts
+src/search/__tests__/graph-enricher.test.ts
+src/search/__tests__/query-engine.test.ts
+src/search/__tests__/similarity.test.ts
+src/search/__tests__/integration.test.ts
+src/commands/index.ts
+src/commands/search.ts
+```
+
+**Modified files (5):**
+```
+src/types/index.ts          ← new search types (SearchResult, IndexMetadata with status + failed_files)
+src/core/config.ts          ← SearchConfigSchema (no max_concurrent_requests)
+src/core/errors.ts          ← new error codes (including search_index_corrupted)
+src/cli.ts                  ← register index + search commands
+package.json                ← lancedb@0.14.3 (pinned) + esbuild externals
+.gitignore                  ← exclude vector_index/
+```
+
+**Runtime artifacts (generated, gitignored):**
+```
+tasks-management/graph/vector_index/    ← LanceDB data directory
+tasks-management/graph/vector_index/index-meta.json  ← index metadata
+```