@nomos-arc/arc 0.1.0

package/docs/map/ATOMIC_BLUEPRINT.md

@@ -0,0 +1,1349 @@
+# Atomic Remediation Blueprint — Semantic Graph (`arc map` / `arc show map`)
+
+**Source Plan:** `docs/map/semantic_master_plan.md`
+**Red Team Audit:** `docs/map/RED_TEAM_REPORT.md`
+**Status:** Re-engineered. All 4 blockers neutralized, 8 ambiguities resolved, 6 resilience gaps closed.
+
+---
+
+## 1. Executive Summary of Fixes
+
+| Red Team Finding | Resolution | Affected Steps |
+|---|---|---|
+| **BLK-1**: tree-sitter native binary + esbuild = MODULE_NOT_FOUND | Switch to `web-tree-sitter` (WASM). Eliminates native `.node` binding entirely. WASM bundles cleanly with esbuild or loads from `node_modules` without path issues. Post-build verification step added. | 0.2, 2.1, 2.3, Final Check |
+| **BLK-2**: No file-level locking on `project_map.json` | Use `proper-lockfile` on every read-modify-write cycle of `project_map.json`. Same package already used in `src/core/state.ts`. | 5.1j |
+| **BLK-3**: `GraphBuilder.build()` mutates without clearing stale data | `build()` now resets `dependencies = []`, `dependents = []`, `depth = 0` on every `FileNode` before computing the graph. Explicit step added. | 3.2 |
+| **BLK-4/AMB-1**: Kahn's algorithm direction misleading | Clarified: in-degree = `dependents.length` (files that import this node). Depth 0 = nobody imports this file. Direction documented inline in code and plan. | 3.2 |
+| **AMB-2**: SemanticEnricher content source unspecified | Enricher reads file content from disk via `fs/promises.readFile()`. Content is NOT carried from `ScanResult`. Explicit re-read per file. | 4.1 |
+| **AMB-3**: tree-sitter-typescript ESM vs CJS | Eliminated by switching to `web-tree-sitter` with `.wasm` grammar files. Uses `await Parser.init()` + `Language.load(wasmPath)`. No CJS/ESM ambiguity. | 2.1 |
+| **AMB-4**: `ImportResolver` uses sync `fs.existsSync` | `resolve()` is now `async`. Uses `fs.access()` with a `Set<string>` cache populated from the known-files set. Zero sync filesystem calls. | 3.1 |
+| **AMB-5**: ContractWriter assumes parent directory exists | Added `fs.mkdir(dir, { recursive: true })` before every `.semantic.md` write. Handles all edge cases. | 4.2 |
+| **AMB-6**: Exit code 2 semantics | Changed partial-success exit code from `2` to `10`. Avoids Unix/Bash convention collision. | 5.2 |
+| **AMB-7**: `readArchitecturalConstraints` path resolution | All `contextFiles` are normalized to project-root-relative paths using `path.relative(projectRoot, path.resolve(projectRoot, contextFile))` before map lookup. | 5.4b |
+| **AMB-8**: HTML template JSON escaping — XSS surface | `JSON.stringify()` output is post-processed: replace `</` with `<\/` and `${` with `\\${`. Prevents `</script>` injection and template literal breakout. | 6.2a |
+| **GAP-1**: No timeout on tree-sitter parse | Files exceeding 500KB are skipped with a warning before parsing. `web-tree-sitter` WASM parsing is inherently sandboxed but the size guard prevents memory exhaustion. | 2.1 |
+| **GAP-2**: AI failure loses all scan/parse work | Map is written to disk with `semantic: null` BEFORE AI enrichment begins. AI enrichment then updates the map in a second write. Crash-safe. | 5.1 |
+| **GAP-3**: No SIGINT/SIGTERM handler | Pipeline registers a `process.on('SIGINT')` handler that sets a cancellation flag. Enrichment loop checks the flag between batches and writes partial map on abort. | 5.1 |
+| **GAP-4**: CDN dependency for visualization — offline failure | Cytoscape.js is bundled inline (~500KB minified) via a build-time fetch + embed. Fallback: `<noscript>` tag with a text-based file list. | 6.2a |
+| **GAP-5**: `migrateProjectMap()` no forward compatibility | Added version ceiling check: if `schema_version > CURRENT_SCHEMA_VERSION`, throw `NomosError('graph_parse_error', 'Map was created by a newer version of arc. Please upgrade.')`. | 1.3 |
+| **GAP-6**: Circular dependency — incomplete cycle reporting | Added Tarjan's SCC post-Kahn's to extract distinct cycles. Each cycle is logged with its full path. Nodes are grouped by SCC for accurate depth assignment. | 3.2 |
+
+---
+
+## 2. 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/core/graph/` does not exist | `ls src/core/graph/ 2>&1` | "No such file or directory" |
+| PF-6 | `proper-lockfile` already installed | `grep 'proper-lockfile' package.json` | Match found (used in `src/core/state.ts`) |
+| PF-7 | Git working tree clean | `git status --porcelain` | Empty output (or acknowledged untracked) |
+
+---
+
+## 3. Atomic Execution Sequence
+
+### Phase 0: Prerequisites — Dependency & Configuration Setup
+
+---
+
+#### Step 0.1: Install runtime dependencies
+
+**Pre-Condition:** PF-1 through PF-7 pass. `package.json` exists at project root.
+
+**Action:**
+```bash
+npm install fast-glob gitignore-parser p-limit open cytoscape
+```
+Note: `cytoscape` is a runtime dependency used by `html-template.ts` to read `cytoscape.min.js` from `node_modules` and embed it inline in the generated HTML (see WATCH-2 in Step 6.2a). It is NOT bundled by esbuild.
+
+**Validation:**
+```bash
+node -e "import('fast-glob').then(()=>console.log('ok'))" # → "ok"
+node -e "import('p-limit').then(()=>console.log('ok'))"   # → "ok"
+grep '"fast-glob"' package.json                            # → match in dependencies
+grep '"open"' package.json                                 # → match in dependencies
+grep '"cytoscape"' package.json                            # → match in dependencies (WATCH-2)
+```
+
+**Rollback:** `npm uninstall fast-glob gitignore-parser p-limit open`
+
+**Idempotency:** `npm install` is idempotent — re-running with already-installed packages is a no-op.
+
+---
+
+#### Step 0.2: Install parsing & AI dependencies + update esbuild externals
+
+**Pre-Condition:** Step 0.1 complete. `package.json` contains `fast-glob` in dependencies.
+
+**Action:**
+1. Install WASM-based parser (NOT native `tree-sitter`):
+   ```bash
+   npm install web-tree-sitter @google/generative-ai
+   ```
+2. **[WATCH-1 PROTOCOL] WASM Grammar Acquisition — Deterministic 3-Tier Fallback:**
+
+   WASM grammar files are NOT shipped with `web-tree-sitter` itself. They must be obtained separately. The following tiers are tried **in order** — stop at the first that succeeds:
+
+   **Tier A — `tree-sitter-wasms` npm package (preferred):**
+   ```bash
+   npm install tree-sitter-wasms
+   ```
+   Verify the exact files exist:
+   ```bash
+   ls node_modules/tree-sitter-wasms/out/tree-sitter-typescript.wasm  # → exists
+   ls node_modules/tree-sitter-wasms/out/tree-sitter-tsx.wasm         # → exists
+   ```
+   If BOTH files exist → Tier A succeeds. Set grammar resolution paths:
+   ```typescript
+   // In parser.ts — grammar paths resolved at runtime from node_modules
+   const GRAMMAR_BASE = path.join(
+     path.dirname(require.resolve('tree-sitter-wasms/package.json')),
+     'out'
+   );
+   const TS_WASM  = path.join(GRAMMAR_BASE, 'tree-sitter-typescript.wasm');
+   const TSX_WASM = path.join(GRAMMAR_BASE, 'tree-sitter-tsx.wasm');
+   ```
+   Note: `require.resolve` works in both ESM (via `createRequire`) and CJS. This avoids fragile relative paths and survives hoisted `node_modules`.
+
+   **Tier B — Official tree-sitter GitHub Release artifacts:**
+   If `tree-sitter-wasms` does not provide the files (package deprecated, renamed, or missing grammars):
+   ```bash
+   mkdir -p src/core/graph/grammars
+   # Download pinned versions from tree-sitter-typescript releases
+   curl -L -o src/core/graph/grammars/tree-sitter-typescript.wasm \
+     "https://github.com/nicolo-ribaudo/tree-sitter-typescript/releases/download/v0.23.2/tree-sitter-typescript.wasm"
+   curl -L -o src/core/graph/grammars/tree-sitter-tsx.wasm \
+     "https://github.com/nicolo-ribaudo/tree-sitter-typescript/releases/download/v0.23.2/tree-sitter-tsx.wasm"
+   ```
+   Verify:
+   ```bash
+   file src/core/graph/grammars/tree-sitter-typescript.wasm  # → "WebAssembly (wasm) binary module"
+   file src/core/graph/grammars/tree-sitter-tsx.wasm          # → "WebAssembly (wasm) binary module"
+   ```
+   Grammar paths in `parser.ts`:
+   ```typescript
+   const GRAMMAR_BASE = path.join(path.dirname(fileURLToPath(import.meta.url)), 'grammars');
+   ```
+
+   **Tier C — Build from source (last resort):**
+   ```bash
+   npm install -g tree-sitter-cli
+   git clone --depth 1 https://github.com/nicolo-ribaudo/tree-sitter-typescript.git /tmp/ts-grammar
+   cd /tmp/ts-grammar/typescript && tree-sitter build --wasm
+   cd /tmp/ts-grammar/tsx && tree-sitter build --wasm
+   cp /tmp/ts-grammar/typescript/tree-sitter-typescript.wasm src/core/graph/grammars/
+   cp /tmp/ts-grammar/tsx/tree-sitter-tsx.wasm src/core/graph/grammars/
+   rm -rf /tmp/ts-grammar
+   ```
+
+   **CRITICAL GATE — Grammar Load Smoke Test:**
+   Regardless of which tier succeeded, run this Node.js script to confirm WASM grammars actually load:
+   ```bash
+   node --input-type=module -e "
+     import Parser from 'web-tree-sitter';
+     await Parser.init();
+     const p = new Parser();
+     // Adjust path based on which tier was used
+     const lang = await Parser.Language.load('<path-to-tree-sitter-typescript.wasm>');
+     p.setLanguage(lang);
+     const tree = p.parse('const x: number = 1;');
+     console.log(tree.rootNode.type === 'program' ? 'GRAMMAR_OK' : 'GRAMMAR_FAIL');
+   "
+   ```
+   Expected output: `GRAMMAR_OK`. If output is `GRAMMAR_FAIL` or the script throws → STOP. Do not proceed to Phase 2.
+
+3. In `package.json`, update the `"build"` script to append:
+   ```
+   --external:@google/generative-ai --external:open
+   ```
+   Note: `web-tree-sitter` is pure JS/WASM — it does NOT need `--external`. This eliminates BLK-1 entirely.
+
+4. **Grammar path abstraction** — To insulate `parser.ts` from which tier was used, create a one-line config constant:
+   ```typescript
+   // src/core/graph/grammar-paths.ts (new file, ~10 lines)
+   import { createRequire } from 'node:module';
+   import path from 'node:path';
+   import { fileURLToPath } from 'node:url';
+   import fs from 'node:fs';
+
+   const __dirname = path.dirname(fileURLToPath(import.meta.url));
+   const require = createRequire(import.meta.url);
+
+   function resolveGrammar(name: string): string {
+     // Tier A: try tree-sitter-wasms
+     try {
+       const wasmsBase = path.join(
+         path.dirname(require.resolve('tree-sitter-wasms/package.json')),
+         'out'
+       );
+       const wasmPath = path.join(wasmsBase, name);
+       if (fs.existsSync(wasmPath)) return wasmPath;
+     } catch { /* package not installed */ }
+
+     // Tier B/C: local grammars directory
+     const localPath = path.join(__dirname, 'grammars', name);
+     if (fs.existsSync(localPath)) return localPath;
+
+     throw new Error(
+       `WASM grammar "${name}" not found. Run Step 0.2 grammar acquisition protocol.`
+     );
+   }
+
+   export const TS_WASM_PATH  = resolveGrammar('tree-sitter-typescript.wasm');
+   export const TSX_WASM_PATH = resolveGrammar('tree-sitter-tsx.wasm');
+   ```
+   `parser.ts` imports `{ TS_WASM_PATH, TSX_WASM_PATH }` from `./grammar-paths.js` — single source of truth.
+
+**Validation:**
+```bash
+node -e "import('web-tree-sitter').then(()=>console.log('ok'))"  # → "ok"
+grep 'external:@google/generative-ai' package.json               # → match
+grep 'external:open' package.json                                 # → match
+npm run build                                                     # → exit code 0
+node dist/cli.js --help                                           # → shows help (BLK-1 post-build check)
+# WATCH-1 CRITICAL GATE:
+node --input-type=module -e "import Parser from 'web-tree-sitter'; await Parser.init(); console.log('WASM_INIT_OK')"
+# → WASM_INIT_OK
+```
+
+**Rollback:** Revert `package.json` to git HEAD (`git checkout package.json`), then `npm install`. Remove `src/core/graph/grammars/` if created. `npm uninstall tree-sitter-wasms` if installed.
+
+**Idempotency:** `npm install` is idempotent. Grammar file resolution is deterministic — `resolveGrammar()` checks existence before returning. Build script append is guarded by checking if flag already exists.
+
+---
+
+#### Step 0.3: Add new `NomosErrorCode` values
+
+**Pre-Condition:** `src/core/errors.ts` exists. Contains `NomosErrorCode` union type.
+
+**Action:** Add four new error code literals to the `NomosErrorCode` union type, immediately after `'certificate_invalid'`:
+```typescript
+| 'graph_map_not_found'
+| 'graph_parse_error'
+| 'graph_ai_key_missing'
+| 'graph_write_failed'
+```
+
+**Validation:**
+```bash
+grep 'graph_map_not_found' src/core/errors.ts  # → exactly 1 match
+grep 'graph_write_failed' src/core/errors.ts   # → exactly 1 match
+npx tsc --noEmit                               # → exit code 0
+```
+
+**Rollback:** `git checkout src/core/errors.ts`
+
+**Idempotency:** Check if `'graph_map_not_found'` already exists before inserting. If present, skip.
+
+---
+
+#### Step 0.4: Update `.gitignore`
+
+**Pre-Condition:** `.gitignore` exists at project root.
+
+**Action:** Append (if not already present):
+```
+*.semantic.md
+tasks-management/graph/
+.project-map.lock
+```
+
+**Validation:**
+```bash
+grep '*.semantic.md' .gitignore           # → exactly 1 match
+grep 'tasks-management/graph/' .gitignore # → exactly 1 match
+grep '.project-map.lock' .gitignore       # → exactly 1 match (WATCH-3: lockfile artifact)
+```
+
+**Rollback:** Remove appended lines manually.
+
+**Idempotency:** `grep` check before appending. If lines exist, skip.
+
+---
+
+### Phase 1: Foundation — Types, Schema, and File Discovery
+
+**Gate:** Phase 0 complete (all 4 steps verified).
+
+---
+
+#### Step 1.1: Define all Semantic Graph types
+
+**Pre-Condition:** `src/types/index.ts` exists and compiles.
+
+**Action:** Append after a `// ─── Semantic Graph Types ───` section comment:
+- `export interface SymbolEntry { name: string; kind: 'class' | 'function' | 'method' | 'interface' | 'type' | 'enum' | 'variable' | 'export'; line: number; end_line: number | null; signature: string | null; exported: boolean; }`
+- `export interface ImportEntry { source: string; resolved: string | null; symbols: string[]; is_external: boolean; }`
+- `export interface SemanticInfo { overview: string; purpose: string; key_logic: string[]; usage_context: string[]; source_hash: string; enriched_at: string; model: string; }`
+- `export interface FileNode { file: string; hash: string; language: string; symbols: SymbolEntry[]; imports: ImportEntry[]; dependents: string[]; dependencies: string[]; depth: number; last_parsed_at: string | null; semantic: SemanticInfo | null; }`
+- `export interface ProjectMap { schema_version: 1; generated_at: string; root: string; files: Record<string, FileNode>; stats: { total_files: number; total_symbols: number; total_edges: number; core_modules: string[]; }; }`
+
+**Validation:**
+```bash
+npx tsc --noEmit                                      # → exit code 0
+grep 'export interface FileNode' src/types/index.ts   # → exactly 1 match
+grep 'export interface ProjectMap' src/types/index.ts # → exactly 1 match
+```
+
+**Rollback:** Remove appended block.
+
+**Idempotency:** Check if `interface FileNode` exists before appending.
+
+---
+
+#### Step 1.2: Add `graph` section to NomosConfig and GraphConfigSchema
+
+**Pre-Condition:** Step 1.1 complete. `src/types/index.ts` has `NomosConfig` interface. `src/core/config.ts` has `NomosConfigSchema`.
+
+**Action:**
+1. In `src/types/index.ts`, add `graph` property to `NomosConfig`:
+   ```typescript
+   graph: {
+     exclude_patterns: string[];
+     ai_enrichment: boolean;
+     ai_model: string;
+     ai_concurrency: number;
+     ai_requests_per_minute: number;
+     max_file_chars: number;
+     core_modules_count: number;
+     output_dir: string;
+   };
+   ```
+2. In `src/core/config.ts`, define `GraphConfigSchema`:
+   ```typescript
+   const GraphConfigSchema = z.object({
+     exclude_patterns: z.array(z.string()).default(['node_modules', 'dist', '*.test.*', '*.spec.*', '*.semantic.md']),
+     ai_enrichment: z.boolean().default(true),
+     ai_model: z.string().default('gemini-1.5-flash'),
+     ai_concurrency: z.number().int().positive().default(5),
+     ai_requests_per_minute: z.number().int().positive().default(14),
+     max_file_chars: z.number().positive().default(4000),
+     core_modules_count: z.number().int().positive().default(10),
+     output_dir: z.string().default('tasks-management/graph'),
+   });
+   ```
+3. Add to `NomosConfigSchema`: `graph: GraphConfigSchema.default(() => GraphConfigSchema.parse({}))`
+
+**Validation:**
+```bash
+npx tsc --noEmit                                       # → exit code 0
+grep 'GraphConfigSchema' src/core/config.ts            # → at least 2 matches
+npx vitest run                                         # → all existing tests pass
+```
+
+**Rollback:** `git checkout src/types/index.ts src/core/config.ts`
+
+---
+
+#### Step 1.3: Implement `ProjectMapSchema`, `migrateProjectMap()`, and `readProjectMap()`
+
+**Pre-Condition:** Step 1.1 complete. Types available.
+
+**Target File:** `src/core/graph/map-schema.ts` (new)
+
+**Action:** Create with:
+1. Zod schemas for `SymbolEntrySchema`, `ImportEntrySchema`, `SemanticInfoSchema`, `FileNodeSchema`, `ProjectMapSchema`.
+2. `CURRENT_SCHEMA_VERSION = 1` constant (exported).
+3. `migrations: Record<number, (raw: unknown) => unknown>` — empty.
+4. `migrateProjectMap(raw: unknown): ProjectMap`:
+   - **[GAP-5 FIX]** First check: `if (raw.schema_version > CURRENT_SCHEMA_VERSION) throw new NomosError('graph_parse_error', 'Map was created by a newer version of arc. Please upgrade.')`
+   - Then apply migrations from current version to `CURRENT_SCHEMA_VERSION`.
+   - Validate with `ProjectMapSchema.parse()`.
+5. `readProjectMap(mapPath: string): Promise<ProjectMap | null>`:
+   - Read JSON from `mapPath` using `fs/promises`.
+   - Return `null` on `ENOENT`.
+   - Throw `NomosError('graph_parse_error', ...)` on parse/validation failure.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                          # → exit code 0
+grep 'export const CURRENT_SCHEMA_VERSION' src/core/graph/map-schema.ts   # → 1 match
+grep 'Please upgrade' src/core/graph/map-schema.ts                        # → 1 match (GAP-5)
+grep 'export function migrateProjectMap' src/core/graph/map-schema.ts     # → 1 match
+grep 'export async function readProjectMap' src/core/graph/map-schema.ts  # → 1 match
+```
+
+**Rollback:** `rm src/core/graph/map-schema.ts`
+
+---
+
+#### Step 1.4: Implement `FileScanner`
+
+**Pre-Condition:** Step 0.1 complete (`fast-glob`, `gitignore-parser` installed). Step 1.1 complete (types defined).
+
+**Target File:** `src/core/graph/scanner.ts` (new)
+
+**Action:** Create `FileScanner` class:
+1. Constructor: `(projectRoot: string, config: NomosConfig['graph'], logger: Logger)`
+2. Module-level `LANGUAGE_MAP` constant (exported): `.ts`, `.tsx`, `.mts`, `.cts`, `.d.ts`, `.js`, `.mjs`, `.cjs`, `.jsx`, `.py`, `.go`, `.rs`
+3. `async scan(existingMap: ProjectMap | null, force: boolean, globPatterns?: string[]): Promise<ScanResult>`
+   - `ScanResult = { files: Map<string, { file: string; hash: string; language: string; content: string }>; carried: Map<string, FileNode> }`
+   - Read `.gitignore` via `gitignore-parser`. If missing, use empty ignore list.
+   - `fast-glob` with patterns `**/*`, applying gitignore + `config.exclude_patterns` as `ignore`.
+   - For each file: check extension in `LANGUAGE_MAP` (skip unknown). Compute `sha256:<hex>` via `node:crypto`. On `EACCES`/`ENOENT`, log warning, skip.
+   - **[GAP-1 FIX]** Skip files exceeding 500KB (`stat.size > 512000`) with warning: `[nomos:graph:warn] Skipping {file} — exceeds 500KB size limit`.
+   - Incremental: if `existingMap` and `!force`, compare hash. Unchanged → `carried`. Changed → `files`.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                            # → exit code 0
+grep 'export class FileScanner' src/core/graph/scanner.ts   # → 1 match
+grep '512000' src/core/graph/scanner.ts                     # → 1 match (GAP-1 size guard)
+```
+
+**Rollback:** `rm src/core/graph/scanner.ts`
+
+---
+
+#### Step 1.5: Test `FileScanner`
+
+**Pre-Condition:** Step 1.4 complete.
+
+**Target File:** `src/core/graph/__tests__/scanner.test.ts` (new)
+
+**Action:** vitest tests covering:
+1. Finds `.ts` and `.js` files in a tmp directory.
+2. Computes correct SHA-256 hashes.
+3. Detects correct language from extension.
+4. Excludes `node_modules` directory.
+5. Handles unreadable file gracefully (no throw).
+6. Skips files with unknown extensions (`.png`).
+7. Carries forward unchanged `FileNode` when `force=false`.
+8. Re-scans all files when `force=true` even if hashes match.
+9. **[GAP-1]** Skips files exceeding 500KB.
+
+**Validation:** `npx vitest run src/core/graph/__tests__/scanner.test.ts` — all pass.
+
+**Rollback:** Delete test file and re-evaluate Step 1.4.
+
+---
+
+### Phase 2: AST Parsing & Symbol Extraction
+
+**Gate:** Phase 1 complete (Steps 1.1–1.5 verified).
+
+---
+
+#### Step 2.1: Implement `ASTParser` — WASM-based grammar + symbol extraction
+
+**Pre-Condition:** Step 0.2 complete (`web-tree-sitter` installed, WASM grammars available).
+
+**Target File:** `src/core/graph/parser.ts` (new)
+
+**Action:** Create `ASTParser` class:
+1. **[BLK-1 FIX + WATCH-1]** Constructor uses `web-tree-sitter` (WASM), NOT native `tree-sitter`. Grammar paths are resolved via the `grammar-paths.ts` abstraction layer (created in Step 0.2):
+   ```typescript
+   import Parser from 'web-tree-sitter';
+   import { TS_WASM_PATH, TSX_WASM_PATH } from './grammar-paths.js';
+
+   export class ASTParser {
+     private parser: Parser | null = null;
+     private tsLang: Parser.Language | null = null;
+     private tsxLang: Parser.Language | null = null;
+
+     async init(): Promise<void> {
+       await Parser.init();
+       this.parser = new Parser();
+       // Grammar paths resolved by grammar-paths.ts (Tier A: node_modules, Tier B/C: local)
+       this.tsLang = await Parser.Language.load(TS_WASM_PATH);
+       this.tsxLang = await Parser.Language.load(TSX_WASM_PATH);
+     }
+   ```
+   No `__dirname` hacks, no conditional path resolution in parser code. `grammar-paths.ts` handles all tier fallback logic.
+2. `parse(filePath: string, content: string, language: string): ParseResult` where `ParseResult = { symbols: SymbolEntry[]; imports: ImportEntry[] }`.
+3. **[AMB-3 FIX]** Grammar selection: No CJS/ESM ambiguity. `web-tree-sitter` loads `.wasm` files uniformly:
+   - `.tsx` → `this.tsxLang`
+   - All other TS variants → `this.tsLang`
+   - JS files → `this.tsLang` (TypeScript grammar parses JS superset)
+   - Unsupported languages → return empty `{ symbols: [], imports: [] }` with debug log.
+4. Error-node threshold: count `ERROR` node chars. If `errorChars / totalChars > 0.20`, log warning, return empty result.
+5. Symbol extraction via tree walk (unchanged from original plan):
+   - `function_declaration`, `arrow_function` → `kind: 'function'`
+   - `class_declaration` → `kind: 'class'`; child `method_definition` → `kind: 'method'`, `name: 'ClassName.methodName'`
+   - `interface_declaration` → `kind: 'interface'`
+   - `type_alias_declaration` → `kind: 'type'`
+   - `enum_declaration` → `kind: 'enum'`
+   - Top-level `lexical_declaration` with `export` parent → `kind: 'variable'`
+6. Line extraction: `line = node.startPosition.row + 1`, `end_line = node.endPosition.row + 1`.
+7. Signature capture per original plan.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                           # → exit code 0
+grep 'web-tree-sitter' src/core/graph/parser.ts            # → at least 1 match
+grep 'export class ASTParser' src/core/graph/parser.ts     # → 1 match
+grep 'async init' src/core/graph/parser.ts                 # → 1 match (WASM requires async init)
+```
+
+**Rollback:** `rm src/core/graph/parser.ts`
+
+---
+
+#### Step 2.2: Implement import extraction in `ASTParser`
+
+**Pre-Condition:** Step 2.1 complete.
+
+**Target File:** `src/core/graph/parser.ts` (modify)
+
+**Action:** In the `parse()` tree walk, add:
+1. `import_statement` → extract `source` from string literal, `symbols` from named specifiers. Default/namespace → empty `symbols`.
+2. `call_expression` with callee `require` → extract `source` from first argument string literal.
+3. Create `ImportEntry` with `resolved: null`, `is_external: false` (resolver corrects later).
+
+**Validation:**
+```bash
+npx tsc --noEmit                                    # → exit code 0
+grep 'import_statement' src/core/graph/parser.ts    # → at least 1 match
+```
+
+**Rollback:** Revert import extraction changes only (keep Step 2.1).
+
+---
+
+#### Step 2.3: Test `ASTParser`
+
+**Pre-Condition:** Steps 2.1 + 2.2 complete.
+
+**Target File:** `src/core/graph/__tests__/parser.test.ts` (new)
+
+**Action:** vitest tests covering:
+1. Function declarations (name, line, end_line, exported, signature).
+2. Class + method extraction (`ClassName.methodName`).
+3. Interface, type, enum declarations.
+4. `export const` variable declarations.
+5. TSX grammar selection for `.tsx` extension (test with JSX content).
+6. Error-node threshold: malformed TS (> 20% errors) → empty arrays.
+7. Import statements with named symbols.
+8. `require()` calls.
+9. `resolved` is always `null` at this stage.
+
+**Important:** `ASTParser.init()` must be called in `beforeAll` (WASM init is async).
+
+**Validation:** `npx vitest run src/core/graph/__tests__/parser.test.ts` — all pass.
+
+**Rollback:** Fix failing tests. If WASM loading fails, verify Step 0.2 grammar file paths.
+
+---
+
+### Phase 3: Import Resolution & Dependency Graph
+
+**Gate:** Phase 2 complete (Steps 2.1–2.3 verified).
+
+---
+
+#### Step 3.1: Implement `ImportResolver` (async)
+
+**Pre-Condition:** Phase 2 complete.
+
+**Target File:** `src/core/graph/resolver.ts` (new)
+
+**Action:** Create `ImportResolver` class:
+1. Constructor: `(projectRoot: string, logger: Logger)` — reads `tsconfig.json` to extract `compilerOptions.paths`. Missing/no-paths → empty alias map.
+2. **[AMB-4 FIX]** `async resolve(importSource: string, importerFile: string, knownFiles: Set<string>): Promise<ResolveResult>` where `ResolveResult = { resolved: string | null; is_external: boolean }`.
+3. Resolution logic (in order):
+   a. **External check:** Does not start with `.`, `/`, or matched tsconfig alias → `{ resolved: null, is_external: true }`.
+   b. **Tsconfig alias:** Match against `compilerOptions.paths` keys (supporting `*` wildcard). Substitute capture into first value pattern. Continue to relative resolution.
+   c. **Relative resolution:** Compute absolute path from importer's directory. Try extensions: `.ts`, `.tsx`, `.js`. Then `/index.ts`, `/index.tsx`, `/index.js`. Check each against `knownFiles` set. First match → `{ resolved: match, is_external: false }`.
+   d. **Path traversal guard:** If resolved absolute path falls outside `projectRoot` → `{ resolved: null, is_external: true }`. Log warning.
+   e. **Unresolvable:** Log `[nomos:graph:warn] Cannot resolve import '{source}' from '{importer}'` → `{ resolved: null, is_external: false }`.
+4. **[AMB-4 FIX + WATCH-4] `knownFiles` Set Contract:**
+
+   The `knownFiles: Set<string>` parameter replaces ALL filesystem calls. This is O(1) per lookup vs O(1) amortized with syscall overhead. **Critical ordering invariant:**
+
+   > `knownFiles` MUST be populated from BOTH `ScanResult.files` (newly scanned) AND `ScanResult.carried` (unchanged from previous run) BEFORE any `resolve()` call.
+
+   The Set is constructed in `MapPipeline.run()` (Step 5.1) as follows:
+   ```typescript
+   // Step 5.1g — build knownFiles BEFORE resolution
+   const knownFiles = new Set<string>();
+   for (const key of parsedFiles.keys()) knownFiles.add(key);    // newly parsed
+   for (const key of carriedFiles.keys()) knownFiles.add(key);   // unchanged from prev run
+   ```
+
+   **Why both sources matter:** If only `parsedFiles` is included, carried-forward files (unchanged since last run) become invisible to the resolver. Import `./utils/hash` from a changed file would fail to resolve to `src/utils/hash.ts` if that file was unchanged — a silent, incremental-only bug.
+
+   **The resolver NEVER calls `fs.existsSync`, `fs.access`, `fs.stat`, or any filesystem API.** All existence checks use `knownFiles.has(candidatePath)`. The `async` signature exists solely for interface consistency — the implementation is synchronous in practice.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                 # → exit code 0
+grep 'export class ImportResolver' src/core/graph/resolver.ts    # → 1 match
+grep 'async resolve' src/core/graph/resolver.ts                  # → 1 match (AMB-4)
+grep -c 'existsSync' src/core/graph/resolver.ts                  # → 0 matches (AMB-4 verified)
+```
+
+**Rollback:** `rm src/core/graph/resolver.ts`
+
+---
+
+#### Step 3.2: Implement `GraphBuilder`
+
+**Pre-Condition:** Step 3.1 complete.
+
+**Target File:** `src/core/graph/builder.ts` (new)
+
+**Action:** Create `GraphBuilder` class:
+1. Constructor: `(config: NomosConfig['graph'], logger: Logger)`
+2. `build(fileNodes: Map<string, FileNode>): { total_files: number; total_symbols: number; total_edges: number; core_modules: string[] }` — mutates `FileNode` objects in-place.
+3. Logic:
+   a. **[BLK-3 FIX — MANDATORY]** Reset ALL graph-computed fields before building:
+      ```typescript
+      for (const node of fileNodes.values()) {
+        node.dependencies = [];
+        node.dependents = [];
+        node.depth = 0;
+      }
+      ```
+      This prevents stale data accumulation across incremental runs.
+   b. **Adjacency list:** For each file, iterate `imports[]`. For `resolved !== null && !is_external`: add `resolved` to file's `dependencies` Set; add file to target's `dependents` Set. Deduplicate via `Set`, convert to array.
+   c. **[AMB-1/BLK-4 FIX] Kahn's BFS topological sort — DIRECTION CLARIFIED:**
+      ```
+      DIRECTION: in-degree = number of files that IMPORT this node = dependents.length
+      Depth 0: nodes with in-degree 0 (no file imports them — entry points, leaf consumers)
+      Depth N: nodes that become available after all their importers are processed
+      Core utilities (types/index.ts, config.ts) get HIGHEST depth — most files depend on them
+      ```
+      - Compute in-degree for each node: `dependents.length`
+      - Initialize queue with all nodes where `dependents.length === 0` → `depth = 0`
+      - BFS: dequeue node, for each entry in `node.dependencies`: decrement that target's in-degree. If in-degree reaches 0, enqueue with `depth = currentDepth + 1`.
+   d. **[GAP-6 FIX] Cycle detection with Tarjan's SCC:**
+      After Kahn's BFS, if unprocessed nodes remain (in-degree > 0), they contain cycles:
+      - Run **Tarjan's Strongly Connected Components** on the subgraph of remaining nodes.
+      - For each SCC (each is a distinct cycle):
+        - Find max depth among nodes that have edges INTO this SCC from already-processed nodes.
+        - Assign all SCC nodes `depth = maxDepth + 1`.
+        - Log the full cycle path: `[nomos:graph:warn] Circular dependency detected: {a.ts → b.ts → c.ts → a.ts}` (extracted from SCC traversal order).
+   e. **Stats:** `total_files = fileNodes.size`, `total_symbols = sum(symbols.length)`, `total_edges = count of non-external resolved imports`, `core_modules = top N by depth desc` (N = `config.core_modules_count`).
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                 # → exit code 0
+grep 'export class GraphBuilder' src/core/graph/builder.ts       # → 1 match
+grep 'node.dependencies = \[\]' src/core/graph/builder.ts        # → 1 match (BLK-3 reset)
+grep 'node.dependents = \[\]' src/core/graph/builder.ts          # → 1 match (BLK-3 reset)
+grep -i 'tarjan' src/core/graph/builder.ts                       # → at least 1 match (GAP-6)
+grep 'in-degree = dependents' src/core/graph/builder.ts          # → 1 match (AMB-1 direction comment)
+```
+
+**Rollback:** `rm src/core/graph/builder.ts`
+
+---
+
+#### Step 3.3: Test `ImportResolver`
+
+**Pre-Condition:** Step 3.1 complete.
+
+**Target File:** `src/core/graph/__tests__/resolver.test.ts` (new)
+
+**Action:** vitest tests:
+1. `./utils/hash` → `src/utils/hash.ts` (extension append).
+2. `./utils` → `src/utils/index.ts` (index resolution).
+3. Tsconfig alias `@/utils` → `src/utils/index.ts`.
+4. `zod` → external.
+5. `commander` → external.
+6. Path traversal `../../outside-project` → external with warning.
+7. Unresolvable relative → `{ resolved: null, is_external: false }`.
+8. Missing `tsconfig.json` → alias skipped gracefully.
+9. **[AMB-4]** All resolution uses `knownFiles` Set, no filesystem calls.
+10. **[WATCH-4]** Resolver finds a carried-forward file: `knownFiles` contains `src/utils/hash.ts` (from carried map, not freshly scanned) → `./utils/hash` resolves correctly. This confirms the Set includes both new and carried files.
+
+**Validation:** `npx vitest run src/core/graph/__tests__/resolver.test.ts` — all pass.
+
+**Rollback:** Fix tests or re-evaluate Step 3.1.
+
+---
+
+#### Step 3.4: Test `GraphBuilder`
+
+**Pre-Condition:** Step 3.2 complete.
+
+**Target File:** `src/core/graph/__tests__/builder.test.ts` (new)
+
+**Action:** vitest tests:
+1. Chain: A→B→C → depths: A=0, B=1, C=2.
+2. Fan-in: A→C, B→C → C highest depth, A,B = 0.
+3. Forward/reverse edges correctly populated.
+4. 2-node cycle: A↔B → both `depth = max + 1`, warning logged.
+5. 3-node cycle: A→B→C→A → all three get cycle depth, warning with full path.
+6. **[BLK-3]** Incremental: run `build()` twice on same nodes with changed imports → second run does NOT carry stale edges.
+7. **[GAP-6]** Disconnected cycles: A↔B and C↔D with no connection → distinct cycle warnings logged for each.
+8. `core_modules` extraction: top N by depth.
+9. Stats accuracy.
+
+**Validation:** `npx vitest run src/core/graph/__tests__/builder.test.ts` — all pass.
+
+**Rollback:** Fix tests or re-evaluate Step 3.2.
+
+---
+
+### Phase 4: AI Semantic Enrichment
+
+**Gate:** Phase 3 complete (Steps 3.1–3.4 verified).
+
+---
+
+#### Step 4.1: Implement `SemanticEnricher`
+
+**Pre-Condition:** Phase 3 complete. `@google/generative-ai` installed.
+
+**Target File:** `src/core/graph/enricher.ts` (new)
+
+**Action:** Create `SemanticEnricher` class:
+1. Constructor: `(config: NomosConfig['graph'], logger: Logger)` — validates `GEMINI_API_KEY`. Missing + `ai_enrichment=true` → throw `NomosError('graph_ai_key_missing')`. Init `GoogleGenerativeAI` client + `p-limit(config.ai_concurrency)`.
+2. `async enrich(fileNodes: Map<string, FileNode>, cancellationFlag: { cancelled: boolean }): Promise<number>` — returns count of failures. Mutates `FileNode.semantic`.
+3. Logic per file:
+   a. Staleness: skip if `semantic !== null && semantic.source_hash === hash`.
+   b. **[AMB-2 FIX]** Content source: read file from disk via `fs/promises.readFile(path.join(projectRoot, fileNode.file), 'utf-8')`. Do NOT rely on `ScanResult.content` — it may be garbage-collected. Truncate at last complete line before `config.max_file_chars`.
+   c. Prompt: File, Language, Exports, Used by, content, JSON schema instruction (per task spec).
+   d. Gemini call with `responseSchema` for structured output.
+   e. Rate limiting: `p-limit` + minimum gap of `Math.ceil(60000 / config.ai_requests_per_minute)` ms.
+   f. Retry: 429/503 → 3 retries, exponential backoff (2s, 4s, 8s). After 3 failures → `semantic: null`, log error.
+   g. Zod validation on response. Failure → log truncated raw (200 chars), `semantic: null`.
+   h. Populate `SemanticInfo`.
+   i. **[GAP-3 FIX]** Between each batch, check `cancellationFlag.cancelled`. If true, stop processing and return current failure count.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                   # → exit code 0
+grep 'export class SemanticEnricher' src/core/graph/enricher.ts    # → 1 match
+grep 'readFile' src/core/graph/enricher.ts                         # → at least 1 match (AMB-2: reads from disk)
+grep 'cancellationFlag' src/core/graph/enricher.ts                 # → at least 1 match (GAP-3)
+```
+
+**Rollback:** `rm src/core/graph/enricher.ts`
+
+---
+
+#### Step 4.2: Implement `ContractWriter`
+
+**Pre-Condition:** Step 4.1 complete.
+
+**Target File:** `src/core/graph/contract-writer.ts` (new)
+
+**Action:** Create `ContractWriter` class:
+1. Constructor: `(projectRoot: string, logger: Logger)`
+2. `async writeContracts(fileNodes: Map<string, FileNode>): Promise<void>`
+3. Logic per file:
+   a. Skip if `semantic === null`.
+   b. Output path: replace extension with `.semantic.md`.
+   c. Overwrite skip: if `.semantic.md` exists and contains current `source_hash`, skip.
+   d. **[AMB-5 FIX]** Before writing, ensure parent directory exists:
+      ```typescript
+      await fs.mkdir(path.dirname(outputPath), { recursive: true });
+      ```
+   e. Write markdown per template.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                              # → exit code 0
+grep 'export class ContractWriter' src/core/graph/contract-writer.ts          # → 1 match
+grep 'recursive: true' src/core/graph/contract-writer.ts                      # → at least 1 match (AMB-5)
+```
+
+**Rollback:** `rm src/core/graph/contract-writer.ts`
+
+---
+
+#### Step 4.3: Test `SemanticEnricher`
+
+**Pre-Condition:** Step 4.1 complete.
+
+**Target File:** `src/core/graph/__tests__/enricher.test.ts` (new)
+
+**Action:** vitest tests with `vi.mock('@google/generative-ai')`:
+1. Enriches file with `semantic: null` → mock returns valid JSON → populated.
+2. Staleness: matching `source_hash` → skipped.
+3. Zod failure: mock returns `{ overview: 123 }` → `semantic: null`.
+4. Retry on 429: mock throws twice then succeeds → populated.
+5. Missing API key → constructor throws.
+6. All retries exhausted → `semantic: null`.
+7. **[GAP-3]** Cancellation flag set mid-enrichment → stops processing.
+8. **[AMB-2]** Verifies file content is read from disk (mock `fs.readFile`).
+
+**Validation:** `npx vitest run src/core/graph/__tests__/enricher.test.ts` — all pass.
+
+---
+
+#### Step 4.4: Test `ContractWriter`
+
+**Pre-Condition:** Step 4.2 complete.
+
+**Target File:** `src/core/graph/__tests__/contract-writer.test.ts` (new)
+
+**Action:** vitest tests:
+1. Writes `.semantic.md` with correct structure.
+2. Skips when `source_hash` matches.
+3. Overwrites when hash changed.
+4. Skips files with `semantic: null`.
+5. **[AMB-5]** Creates parent directory if missing.
+
+**Validation:** `npx vitest run src/core/graph/__tests__/contract-writer.test.ts` — all pass.
+
+---
+
+### Phase 5: Command, Pipeline, and Integration
+
+**Gate:** Phase 4 complete (Steps 4.1–4.4 verified).
+
+---
+
+#### Step 5.1: Implement `MapPipeline`
+
+**Pre-Condition:** All Phase 1–4 components exist and pass tests.
+
+**Target File:** `src/core/graph/pipeline.ts` (new)
+
+**Action:** Create `MapPipeline` class:
+1. Constructor: `(config: NomosConfig, projectRoot: string, logger: Logger)`
+2. `async run(options: { noAi: boolean; force: boolean; patterns?: string[] }): Promise<{ map: ProjectMap; aiFailures: number }>`
+3. Pipeline flow:
+   a. Read existing map via `readProjectMap()`.
+   b. `FileScanner.scan()` → `files` (need parsing) + `carried` (unchanged).
+   c. If both empty: log warning, return empty map.
+   d. **Init `ASTParser`** — call `await parser.init()` (WASM requires async initialization).
+   e. For each file in `files`: `ASTParser.parse()` → build `FileNode`.
+   f. Merge parsed + carried into `Map<string, FileNode>`.
+   g. **[WATCH-4 — CRITICAL ORDERING]** Build `knownFiles` Set BEFORE resolution:
+      ```typescript
+      // Merge ALL known file paths — both newly parsed and carried forward
+      const allFiles = new Map<string, FileNode>();  // from step f
+      const knownFiles = new Set<string>(allFiles.keys());
+      // knownFiles now contains EVERY file the scanner saw, regardless of parse status
+      ```
+      Then call `ImportResolver.resolve()` for every `ImportEntry`, passing `knownFiles`.
+      `resolve()` is async — use `Promise.all` with `p-limit` if needed.
+      **Invariant:** `knownFiles` is immutable after construction. Never add/remove entries during resolution.
+   h. `GraphBuilder.build()` → mutates graph fields, returns stats.
+   i. **[GAP-2 FIX]** Write map to disk BEFORE AI enrichment (with `semantic: null` for new files):
+      ```typescript
+      const intermediateMap: ProjectMap = { schema_version: 1, generated_at, root, files, stats };
+      await this.writeMap(intermediateMap, mapPath);
+      ```
+   j. If `!noAi`:
+      - **[GAP-3 FIX]** Set up cancellation:
+        ```typescript
+        const cancellation = { cancelled: false };
+        const sigintHandler = () => { cancellation.cancelled = true; };
+        process.on('SIGINT', sigintHandler);
+        ```
+      - Call `SemanticEnricher.enrich(fileNodes, cancellation)`.
+      - Call `ContractWriter.writeContracts(fileNodes)`.
+      - Remove SIGINT handler: `process.removeListener('SIGINT', sigintHandler)`.
+   k. **[BLK-2 FIX + WATCH-3] Atomic write with `proper-lockfile` — Safe on Non-Existent Files:**
+
+      **Problem:** `proper-lockfile` requires the target file to exist before it can acquire a lock. On first run, `project_map.json` does not exist. The original `.catch()` approach (create empty file then re-lock) has a TOCTOU race: two concurrent processes both see the file missing, both create it, and the second `lock()` call may fail or lock a file the first process is about to overwrite.
+
+      **Solution: Lock the DIRECTORY, not the file.** The output directory is created with `mkdir -p` and is guaranteed to exist before any write. A lockfile on the directory serializes all map writes regardless of whether the map file itself exists:
+
+      ```typescript
+      import lockfile from 'proper-lockfile';
+
+      private async writeMap(map: ProjectMap, mapPath: string): Promise<void> {
+        const outDir = path.dirname(mapPath);
+        await fs.mkdir(outDir, { recursive: true });
+
+        // Lock the DIRECTORY — works even when project_map.json doesn't exist yet.
+        // proper-lockfile creates a .lock file (e.g., tasks-management/graph/.lock)
+        // which serializes concurrent arc map invocations.
+        const release = await lockfile.lock(outDir, {
+          lockfilePath: path.join(outDir, '.project-map.lock'),
+          realpath: false,
+          retries: { retries: 10, minTimeout: 200, maxTimeout: 2000 },
+          stale: 60000,  // 60s stale lock — enrichment can be slow
+        });
+
+        try {
+          const tmpPath = `${mapPath}.tmp`;
+          await fs.writeFile(tmpPath, JSON.stringify(map, null, 2), 'utf-8');
+          const fd = await fs.open(tmpPath, 'r+');
+          try { await fd.sync(); } finally { await fd.close(); }
+          await fs.rename(tmpPath, mapPath);
+        } finally {
+          await release();
+        }
+      }
+      ```
+
+      **Why directory locking is correct:**
+      - `outDir` is always created BEFORE lock acquisition → no existence check needed
+      - `lockfilePath` is explicit → no reliance on `proper-lockfile`'s default `.lock` naming
+      - `stale: 60000` is higher than file-lock (30s) because AI enrichment writes can take time
+      - The `.project-map.lock` file is an artifact — add to `.gitignore` in Step 0.4
+      - `rename()` is atomic on POSIX — combined with the directory lock, this is double-safe
+
+      **Additional `.gitignore` entry** (add in Step 0.4):
+      ```
+      .project-map.lock
+      ```
+   l. Count AI failures and return.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                 # → exit code 0
+grep 'export class MapPipeline' src/core/graph/pipeline.ts       # → 1 match
+grep 'proper-lockfile' src/core/graph/pipeline.ts                # → at least 1 match (BLK-2)
+grep 'SIGINT' src/core/graph/pipeline.ts                         # → at least 1 match (GAP-3)
+grep 'writeMap.*intermediateMap' src/core/graph/pipeline.ts      # → pattern present (GAP-2)
+```
+
+**Rollback:** `rm src/core/graph/pipeline.ts`
+
+---
+
+#### Step 5.2: Implement `arc map` command
+
+**Pre-Condition:** Step 5.1 complete.
+
+**Target File:** `src/commands/map.ts` (new)
+
+**Action:** `registerMapCommand(program: Command): void`:
+1. Options: `--no-ai`, `--force`, variadic `[patterns...]`.
+2. Handler:
+   a. `loadConfig()`.
+   b. If `--no-ai` → `config.graph.ai_enrichment = false`.
+   c. `MapPipeline.run()`.
+   d. Print summary: `Mapped {N} files, enriched {M}, {K} skipped`.
+   e. **[AMB-6 FIX]** Exit codes: `0` = success, `1` = fatal error, `10` = partial AI failure (NOT `2`).
+3. Progress on stderr.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                          # → exit code 0
+grep 'registerMapCommand' src/commands/map.ts             # → 1 match
+grep 'exit(10)' src/commands/map.ts                       # → 1 match (AMB-6: not exit(2))
+```
+
+**Rollback:** `rm src/commands/map.ts`
+
+---
+
+#### Step 5.3: Register `arc map` in CLI entry point
+
+**Pre-Condition:** Step 5.2 complete.
+
+**Target File:** `src/cli.ts` (modify)
+
+**Action:**
+1. Add: `import { registerMapCommand } from './commands/map.js';`
+2. Add `registerMapCommand` to registration array.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                # → exit code 0
+grep 'registerMapCommand' src/cli.ts            # → 2 matches (import + usage)
+npx tsx src/cli.ts map --help                   # → shows help
+```
+
+**Rollback:** `git checkout src/cli.ts`
+
+---
+
+#### Step 5.4a: Extend `PromptOptions` with `architecturalConstraints`
+
+**Pre-Condition:** `src/types/index.ts` compiles.
+
+**Action:** Add `architecturalConstraints: string | null;` to `PromptOptions` interface.
+
+**Validation:** `grep 'architecturalConstraints' src/types/index.ts` — 1 match.
+
+**Rollback:** Remove added line.
+
+---
+
+#### Step 5.4b: Implement `readArchitecturalConstraints`
+
+**Pre-Condition:** Steps 1.3 and 5.4a complete.
+
+**Target File:** `src/core/graph/constraints.ts` (new)
+
+**Action:** Export `async function readArchitecturalConstraints(projectRoot: string, outputDir: string, contextFiles: string[]): Promise<string | null>`:
+1. Read `project_map.json`. Missing → return `null`.
+2. Parse with `migrateProjectMap()`.
+3. **[AMB-7 FIX]** Normalize each `contextFile` before lookup:
+   ```typescript
+   const normalizedPath = path.relative(projectRoot, path.resolve(projectRoot, contextFile))
+     .split(path.sep).join('/');  // ensure forward slashes
+   const fileNode = map.files[normalizedPath];
+   ```
+4. Collect dependents with non-null `semantic`, identify consumed symbols.
+5. Build constraint string per spec format.
+6. Return `null` if no constraints found.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                                    # → exit code 0
+grep 'path.relative' src/core/graph/constraints.ts                                  # → at least 1 match (AMB-7)
+grep 'export async function readArchitecturalConstraints' src/core/graph/constraints.ts  # → 1 match
+```
+
+**Rollback:** `rm src/core/graph/constraints.ts`
+
+---
+
+#### Step 5.4c: Wire constraints into `Orchestrator.plan()` and `assemblePrompt()`
+
+**Pre-Condition:** Steps 5.4a + 5.4b complete.
+
+**Target Files:** `src/core/orchestrator.ts`, `src/core/prompt.ts`
+
+**Action:**
+1. In `prompt.ts`: add `[ARCHITECTURAL CONSTRAINTS]` section when `options.architecturalConstraints !== null`.
+2. In `orchestrator.ts`: import `readArchitecturalConstraints`, call before `assemblePrompt`, pass result.
+3. Fix all `PromptOptions` construction sites to include `architecturalConstraints: null`.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                            # → exit code 0
+npx vitest run                                              # → all tests pass
+grep 'ARCHITECTURAL CONSTRAINTS' src/core/prompt.ts         # → 1 match
+```
+
+**Rollback:** Revert both files.
+
+---
+
+#### Step 5.5: Test `MapPipeline` end-to-end
+
+**Pre-Condition:** Steps 5.1–5.4c complete.
+
+**Sub-step 5.5a:** Create test fixture at `test/fixtures/sample-project/` with 8 TS files (per original plan).
+
+**Sub-step 5.5b:** Write `src/core/graph/__tests__/pipeline.test.ts`:
+1. Full pipeline `noAi: true` → 8 files mapped.
+2. `src/types.ts` + `src/utils/index.ts` have highest depth.
+3. `src/main.ts` = depth 0.
+4. Circular pair detected.
+5. Incremental: second run carries all (0 re-parsed).
+6. `--force`: all re-parsed.
+7. `core_modules` correct.
+8. `stats.total_edges` correct.
+9. **[BLK-2]** Concurrent: launch two pipeline runs simultaneously → both complete without corruption (lockfile prevents race).
+10. **[GAP-2]** Kill-safe: verify intermediate map is on disk before enrichment begins.
+
+**Validation:** `npx vitest run src/core/graph/__tests__/pipeline.test.ts` — all pass.
+
+---
+
+#### Step 5.6: Test Architectural Constraint injection
+
+**Pre-Condition:** Step 5.4c complete.
+
+**Target File:** `src/core/__tests__/prompt.test.ts` (modify)
+
+**Action:**
+1. Non-null constraints → `[ARCHITECTURAL CONSTRAINTS]` present.
+2. Null → section absent.
+3. Integration: minimal `project_map.json` → constraint string correct.
+4. **[AMB-7]** Context file with relative path `../src/core/state.ts` → correctly normalized and found.
+5. Missing-from-map file → warning logged, skipped.
+
+**Validation:** `npx vitest run src/core/__tests__/prompt.test.ts` — all pass.
+
+---
+
+### Phase 6: Visualization — `arc show map`
+
+**Gate:** Phase 5 complete (Steps 5.1–5.6 verified).
+
+---
+
+#### Step 6.1: Implement `MapRenderer`
+
+**Pre-Condition:** Phase 5 complete.
+
+**Target File:** `src/core/graph/renderer.ts` (new)
+
+**Action:** Per original plan. `render()` → Cytoscape nodes/edges. `computeColor()` → depth-based gradient.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                               # → exit code 0
+grep 'export class MapRenderer' src/core/graph/renderer.ts     # → 1 match
+```
+
+**Rollback:** `rm src/core/graph/renderer.ts`
+
+---
+
+#### Step 6.2a: Create HTML template — self-contained with inline Cytoscape
+
+**Pre-Condition:** Step 6.1 complete.
+
+**Target File:** `src/core/graph/html-template.ts` (new)
+
+**Action:** `export function generateHtml(mapJson: string, cytoscapeNodes: string, cytoscapeEdges: string): string`:
+1. **[GAP-4 FIX + WATCH-2] Cytoscape.js bundled INLINE — Exact Mechanism:**
+
+   **Problem:** The original plan said "bundle inline" without specifying how. Cytoscape.js minified is ~500KB — too large for a string literal in source code (breaks linters, slows IDE indexing, bloats git diffs).
+
+   **Solution: Runtime read from `node_modules` at generation time.** The `generateHtml()` function reads `cytoscape.min.js` from disk when generating the HTML, NOT at module import time:
+
+   ```typescript
+   // src/core/graph/html-template.ts
+   import fs from 'node:fs';
+   import { createRequire } from 'node:module';
+
+   const require = createRequire(import.meta.url);
+
+   // Lazy-loaded, cached after first call
+   let _cytoscapeSource: string | null = null;
+
+   function getCytoscapeSource(): string {
+     if (_cytoscapeSource) return _cytoscapeSource;
+
+     // Resolve from node_modules — works regardless of hoisting
+     const cytoscapePath = require.resolve('cytoscape/dist/cytoscape.min.js');
+     _cytoscapeSource = fs.readFileSync(cytoscapePath, 'utf-8');
+     return _cytoscapeSource;
+   }
+
+   export function generateHtml(
+     mapJson: string,
+     cytoscapeNodes: string,
+     cytoscapeEdges: string,
+   ): string {
+     const cytoscapeJs = getCytoscapeSource();
+     return `<!DOCTYPE html>
+   <html>
+   <head><meta charset="utf-8"><title>nomos-arc Dependency Graph</title></head>
+   <body>
+     <div id="cy"></div>
+     <noscript><pre>Dependency graph requires JavaScript. Files:\n${textFallback}</pre></noscript>
+     <script>${cytoscapeJs}</script>
+     <script>
+       const PROJECT_MAP = ${safeJson};
+       // ... Cytoscape init, layout, interactivity ...
+     </script>
+   </body>
+   </html>`;
+   }
+   ```
+
+   **Why this approach:**
+   - No build script needed — `cytoscape` is a regular npm dependency
+   - No string literal in source — the 500KB is read at runtime only when `arc show map` runs
+   - `require.resolve()` survives npm hoisting, monorepos, and `node_modules/.pnpm`
+   - Lazy caching means the file is read once per process, not per call
+   - The generated `index.html` is fully self-contained — works offline, no CDN
+
+   **Pre-Requisite Dependency:** Add `cytoscape` as a runtime dependency in Step 0.1:
+   ```bash
+   npm install cytoscape
+   ```
+   (This replaces the CDN dependency. ~500KB is added to `node_modules`, NOT to the esbuild bundle — `html-template.ts` reads it at runtime.)
+
+   **esbuild consideration:** Do NOT add `--external:cytoscape`. The `require.resolve()` call resolves a path at runtime — esbuild does not attempt to bundle it because it's inside a dynamic `readFileSync`, not a static `import`. If esbuild does attempt to bundle it, add `--external:cytoscape` to the build script.
+
+   - Add `<noscript>` fallback with plain-text file listing for offline/no-JS environments.
+2. **[AMB-8 FIX]** JSON embedding with XSS prevention:
+   ```typescript
+   const safeJson = JSON.stringify(map)
+     .replace(/<\//g, '<\\/')    // prevent </script> injection
+     .replace(/\$\{/g, '\\${'); // prevent template literal breakout
+   // Embed as: const PROJECT_MAP = ${safeJson};
+   ```
+3. BFS layout, depth-based coloring, full-viewport CSS — per original plan.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                                  # → exit code 0
+grep 'cytoscape.min' src/core/graph/html-template.ts              # → at least 1 match (GAP-4: inline)
+grep '<\\\\/' src/core/graph/html-template.ts                     # → at least 1 match (AMB-8: XSS fix)
+grep 'noscript' src/core/graph/html-template.ts                   # → at least 1 match (GAP-4: fallback)
+```
+
+**Rollback:** `rm src/core/graph/html-template.ts`
+
+---
+
+#### Step 6.2b: Add context card panel
+
+Per original plan. No changes from Red Team findings.
+
+---
+
+#### Step 6.2c: Add ripple analysis
+
+Per original plan. No changes from Red Team findings.
+
+---
+
+#### Step 6.2d: Add symbol search bar
+
+Per original plan. No changes from Red Team findings.
+
+---
+
+#### Step 6.3: Implement `arc show map` command
+
+**Pre-Condition:** Steps 6.1–6.2d complete.
+
+**Target File:** `src/commands/show.ts` (new)
+
+**Action:** Per original plan. `registerShowCommand(program: Command)`, read map, render, generate HTML, open browser.
+
+**Validation:**
+```bash
+npx tsc --noEmit                                          # → exit code 0
+grep 'registerShowCommand' src/commands/show.ts           # → 1 match
+```
+
+**Rollback:** `rm src/commands/show.ts`
+
+---
+
+#### Step 6.4: Register `arc show map` in CLI
+
+Per original plan. Add import + registration in `src/cli.ts`.
+
+---
+
+#### Step 6.5: Test `MapRenderer`
+
+Per original plan (8 test cases). No changes from Red Team findings.
+
+---
+
+#### Step 6.6: Test `arc show map` command
+
+Per original plan (5 test cases). Add:
+6. **[GAP-4]** Generated HTML does NOT contain `cdnjs.cloudflare.com` (Cytoscape is inline).
+7. **[AMB-8]** Generated HTML with a file path containing `</script>` does not break the page.
+
+---
+
+## 4. Final System Integrity Check
+
+### 4.1 Full Test Suite
+```bash
+npx vitest run
+```
+Expected: all tests pass — 0 failures. 9 new test files + all existing.
+
+### 4.2 Type Check
+```bash
+npx tsc --noEmit
+```
+Expected: exit code 0, no errors.
+
+### 4.3 Build Verification
+```bash
+npm run build
+```
+Expected: `dist/cli.js` produced. No `--external:tree-sitter` needed (WASM bundles natively).
+
+### 4.4 Post-Build Runtime Verification [BLK-1 CRITICAL]
+```bash
+node dist/cli.js map --no-ai --help
+```
+Expected: shows help text. Proves WASM parser loads correctly from built artifact. **This was the exact failure mode BLK-1 identified.**
+
+### 4.5 End-to-End Smoke Test (Structural)
+```bash
+npx tsx src/cli.ts map --no-ai
+```
+Expected: `project_map.json` at `tasks-management/graph/`. Summary printed. Exit code 0.
+```bash
+node -e "const m=JSON.parse(require('fs').readFileSync('tasks-management/graph/project_map.json','utf8')); console.log('files:', Object.keys(m.files).length, 'edges:', m.stats.total_edges, 'version:', m.schema_version)"
+```
+Expected: file count > 0, edge count > 0, version = 1.
+
+### 4.6 Visualization Smoke Test
+```bash
+npx tsx src/cli.ts show map --no-open
+```
+Expected: `index.html` written. Exit code 0.
+```bash
+grep -c 'cytoscape' tasks-management/graph/index.html
+```
+Expected: > 0 matches (inline source, not CDN).
+
+### 4.7 Incremental Run Verification
+```bash
+time npx tsx src/cli.ts map --no-ai  # First run
+time npx tsx src/cli.ts map --no-ai  # Second run
+```
+Expected: second run completes significantly faster (all files carried forward).
+
+### 4.8 Concurrent Execution Safety [BLK-2]
+```bash
+npx tsx src/cli.ts map --no-ai & npx tsx src/cli.ts map --no-ai & wait
+```
+Expected: both complete without error. `project_map.json` is valid JSON. No corruption.
+
+### 4.9 Forward Version Check [GAP-5]
+```bash
+node -e "const fs=require('fs'); const m=JSON.parse(fs.readFileSync('tasks-management/graph/project_map.json','utf8')); m.schema_version=99; fs.writeFileSync('tasks-management/graph/project_map.json',JSON.stringify(m))"
+npx tsx src/cli.ts map --no-ai 2>&1
+```
+Expected: error message containing "newer version" or "Please upgrade".
+
+### 4.10 File Inventory Check
+
+**New files (22 total):**
+```
+src/core/graph/map-schema.ts
+src/core/graph/scanner.ts
+src/core/graph/parser.ts
+src/core/graph/grammar-paths.ts       (WATCH-1: tier-based WASM grammar resolution)
+src/core/graph/resolver.ts
+src/core/graph/builder.ts
+src/core/graph/enricher.ts
+src/core/graph/contract-writer.ts
+src/core/graph/constraints.ts
+src/core/graph/pipeline.ts
+src/core/graph/renderer.ts
+src/core/graph/html-template.ts
+src/core/graph/grammars/              (WASM grammar files — Tier B/C only, not needed if Tier A)
+src/core/graph/__tests__/scanner.test.ts
+src/core/graph/__tests__/parser.test.ts
+src/core/graph/__tests__/resolver.test.ts
+src/core/graph/__tests__/builder.test.ts
+src/core/graph/__tests__/enricher.test.ts
+src/core/graph/__tests__/contract-writer.test.ts
+src/core/graph/__tests__/pipeline.test.ts
+src/core/graph/__tests__/renderer.test.ts
+src/core/graph/__tests__/show.test.ts
+src/commands/map.ts
+src/commands/show.ts
+test/fixtures/sample-project/         (8 files)
+```
+
+**Modified files (6 total):**
+```
+package.json             (new deps + esbuild externals)
+src/core/errors.ts       (4 new error codes)
+src/types/index.ts       (graph types + config + PromptOptions field)
+src/core/config.ts       (GraphConfigSchema)
+src/core/orchestrator.ts (constraint injection)
+src/core/prompt.ts       (architectural constraints section)
+src/cli.ts               (2 new command registrations)
+```
+
+---
+
+## 5. Trade-Off Register
+
+| Decision | Chosen Option | Alternative | Rationale |
+|---|---|---|---|
+| `web-tree-sitter` over native `tree-sitter` | WASM | Native C++ N-API | Eliminates BLK-1 entirely. ~10-20% slower parsing but zero bundling complexity. Production stability > raw speed. |
+| `proper-lockfile` for map writes | File locking | Advisory lock via `flock` | Matches existing codebase pattern (`state.ts`). Cross-platform. Already a dependency. |
+| `knownFiles` Set over `fs.access()` | In-memory lookup | Async filesystem check | O(1) per lookup vs O(1) amortized with syscall overhead. Scanner already knows all files. Zero event-loop blocking. |
+| Inline Cytoscape.js over CDN | ~500KB larger HTML | CDN with offline fallback | Zero external dependencies. Works offline, on air-gapped networks, behind corporate proxies. HTML is generated once, not served repeatedly. |
+| Tarjan's SCC over "assign max+1 to remnants" | Full cycle extraction | Simpler but lossy | Distinct cycles get distinct log entries. Disconnected cycles get correct depth assignment. Marginal code complexity increase for significant diagnostic improvement. |
+| Exit code 10 over exit code 2 | Non-standard but safe | Exit code 2 (Bash convention) | Avoids CI/CD misinterpretation. Exit code 2 = "misuse of shell command" in Bash. Exit code 10 is unambiguous. |
+
+### WATCH Resolutions (Implementation-Time Risks)
+
+| WATCH | Risk | Resolution | Affected Steps |
+|---|---|---|---|
+| **WATCH-1** | `web-tree-sitter` WASM grammars not available via npm | 3-tier deterministic fallback (npm package → GitHub release → build from source) + `grammar-paths.ts` abstraction layer + CRITICAL GATE smoke test | 0.2, 2.1 |
+| **WATCH-2** | Cytoscape.js inline bundling mechanics unspecified | Runtime `readFileSync` from `node_modules/cytoscape/dist/cytoscape.min.js` via `require.resolve()`. Lazy-cached. No string literal in source, no build script. `cytoscape` added as npm dependency in Step 0.1 | 0.1, 6.2a |
+| **WATCH-3** | `proper-lockfile` fails on non-existent file (TOCTOU race) | Lock the output DIRECTORY instead of the file. Directory is guaranteed to exist after `mkdir -p`. Uses explicit `lockfilePath` to `.project-map.lock`. Lockfile added to `.gitignore` | 0.4, 5.1 |
+| **WATCH-4** | `knownFiles` Set must include carried files, not just newly parsed | Explicit construction from `allFiles.keys()` (merged parsed + carried) BEFORE any `resolve()` call. Ordering invariant documented in Step 5.1g. Dedicated test case in resolver tests | 3.1, 5.1, 3.3 |