@nomos-arc/arc 0.1.0

package/docs/map/semantic_master_plan.md

@@ -0,0 +1,705 @@
+# Semantic Graph Master Execution Plan
+
+## 1. Context & Objectives
+- **Source Task:** `docs/map/semantic_graph_task.md`
+- **End Goal:** Implement the `arc map` and `arc show map` commands that transform a raw codebase into a self-aware knowledge base via `project_map.json` — a semantically enriched dependency graph with static analysis (Phases 1–3), optional AI enrichment (Phase 4), architectural constraint injection into `arc plan` (Phase 5), and interactive Cytoscape.js visualization (Phase 6).
+
+## 2. Prerequisite Check
+- [ ] Check 1: Node.js >= 20 is installed — run `node --version` and verify output starts with `v20` or higher.
+- [ ] Check 2: Project root is `/home/ibrahim@creativeft.local/apps/nomos-arc.ai` — run `ls package.json src/cli.ts` and verify both exist.
+- [ ] Check 3: Existing dependencies install cleanly — run `npm install` and verify exit code 0.
+- [ ] Check 4: Existing tests pass before any modifications — run `npx vitest run` and verify 0 failures.
+- [ ] Check 5: Directory `src/core/graph/` does not yet exist — run `ls src/core/graph/ 2>&1` and verify "No such file or directory".
+- [ ] Check 6: Directory `src/core/graph/__tests__/` does not yet exist — same check.
+
+---
+
+## 3. Phased Atomic Execution Plan
+
+### Phase 0: Prerequisites — Dependency & Configuration Setup
+**Dependencies:** `package.json`, `src/core/errors.ts`, `.gitignore`
+
+#### Step 0.1: Install runtime dependencies (`fast-glob`, `gitignore-parser`, `p-limit`, `open`)
+- **Target File:** `package.json`
+- **Action:** Run `npm install fast-glob gitignore-parser p-limit open`
+- **Constraints:** Do not modify any other file. Do not touch devDependencies.
+- **Verification Criteria:** Run `node -e "import('fast-glob').then(()=>console.log('ok'))"` — output is `ok`. Run `cat package.json | grep fast-glob` — line exists under `dependencies`.
+- **Rollback/Failure Action:** Run `npm uninstall fast-glob gitignore-parser p-limit open` and re-evaluate.
+
+#### Step 0.2: Install parsing & AI dependencies + update esbuild externals
+- **Target File:** `package.json`
+- **Action:**
+  1. Run `npm install tree-sitter tree-sitter-typescript @google/generative-ai`
+  2. In `package.json`, update the `"build"` script to append these flags to the existing esbuild command: `--external:tree-sitter --external:tree-sitter-typescript --external:@google/generative-ai --external:open`
+- **Constraints:** Only modify the `"build"` script value. Keep all existing `--external:` flags intact. Do not change any other script.
+- **Verification Criteria:**
+  1. Run `node -e "import('tree-sitter').then(()=>console.log('ok'))"` — output is `ok`.
+  2. Run `grep 'external:tree-sitter' package.json` — matches found.
+  3. Run `grep 'external:open' package.json` — match found.
+  4. Run `npm run build` — exit code 0, `dist/cli.js` is produced.
+- **Rollback/Failure Action:** Revert `package.json` to git HEAD (`git checkout package.json`), then `npm install`.
+
+#### Step 0.3: Add new `NomosErrorCode` values
+- **Target File:** `src/core/errors.ts`
+- **Action:** Add four new error code literals to the `NomosErrorCode` union type, immediately before the closing semicolon:
+  ```
+  | 'graph_map_not_found'
+  | 'graph_parse_error'
+  | 'graph_ai_key_missing'
+  | 'graph_write_failed'
+  ```
+- **Constraints:** Do not modify the `NomosError` class. Do not remove or rename any existing error codes. Insert the new codes after `'certificate_invalid'`.
+- **Verification Criteria:** Run `grep 'graph_map_not_found' src/core/errors.ts` — exactly 1 match. Run `grep 'graph_write_failed' src/core/errors.ts` — exactly 1 match. Run `npx tsc --noEmit` — exit code 0.
+- **Rollback/Failure Action:** Revert file: `git checkout src/core/errors.ts`.
+
+#### Step 0.4: Update `.gitignore` with semantic graph entries
+- **Target File:** `.gitignore`
+- **Action:** Append the following two lines at the end of the file:
+  ```
+  *.semantic.md
+  tasks-management/graph/
+  ```
+- **Constraints:** Do not remove or modify any existing gitignore entries.
+- **Verification Criteria:** Run `grep '*.semantic.md' .gitignore` — exactly 1 match. Run `grep 'tasks-management/graph/' .gitignore` — exactly 1 match.
+- **Rollback/Failure Action:** Remove the appended lines manually.
+
+---
+
+### Phase 1: Foundation — Types, Schema, and File Discovery
+**Dependencies:** Phase 0 complete (all 4 steps verified).
+
+#### Step 1.1: Define all Semantic Graph types in `src/types/index.ts`
+- **Target File:** `src/types/index.ts`
+- **Action:** Append the following type definitions at the end of the file (before any final closing comment, if present). Use the exact interfaces from the task specification:
+  - `SymbolEntry` — `{ name: string; kind: 'class' | 'function' | 'method' | 'interface' | 'type' | 'enum' | 'variable' | 'export'; line: number; end_line: number | null; signature: string | null; exported: boolean; }`
+  - `ImportEntry` — `{ source: string; resolved: string | null; symbols: string[]; is_external: boolean; }`
+  - `SemanticInfo` — `{ overview: string; purpose: string; key_logic: string[]; usage_context: string[]; source_hash: string; enriched_at: string; model: string; }`
+  - `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; }`
+  - `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[]; }; }`
+- **Constraints:** Export all interfaces. Do not modify any existing types. Place under a clear section comment `// ─── Semantic Graph Types ───`.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export interface FileNode' src/types/index.ts` — exactly 1 match. Run `grep 'export interface ProjectMap' src/types/index.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Remove the appended type block and retry.
+
+#### Step 1.2: Add `graph` section to NomosConfig and GraphConfigSchema
+- **Target Files:** `src/types/index.ts`, `src/core/config.ts`
+- **Action:**
+  1. In `src/types/index.ts`, add a `graph` property to the `NomosConfig` interface:
+     ```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` as a Zod object with defaults matching the task spec:
+     ```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 `graph: GraphConfigSchema.default(() => GraphConfigSchema.parse({}))` to the `NomosConfigSchema` Zod object.
+- **Constraints:** Do not modify existing schema fields. Follow the same `.default(() => Schema.parse({}))` pattern used for other nested objects in `config.ts`.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'GraphConfigSchema' src/core/config.ts` — at least 2 matches (definition + usage). Run `npx vitest run` — all existing tests still pass.
+- **Rollback/Failure Action:** Revert both files: `git checkout src/types/index.ts src/core/config.ts`.
+
+#### Step 1.3: Implement `ProjectMapSchema`, `migrateProjectMap()`, and `readProjectMap()`
+- **Target File:** `src/core/graph/map-schema.ts` (new file)
+- **Action:** Create the file with:
+  1. Zod schemas for `SymbolEntrySchema`, `ImportEntrySchema`, `SemanticInfoSchema`, `FileNodeSchema`, `ProjectMapSchema` — each matching the TypeScript interfaces from Step 1.1.
+  2. `migrations` record (`Record<number, (raw: unknown) => unknown>`) — empty for now.
+  3. `migrateProjectMap(raw: unknown): ProjectMap` — applies migrations from `schema_version` to current, then validates with `ProjectMapSchema.parse()`.
+  4. `readProjectMap(mapPath: string): Promise<ProjectMap | null>` — reads JSON from `mapPath`, returns `null` if file does not exist (`ENOENT`), throws `NomosError('graph_parse_error', ...)` on parse/validation failure.
+- **Constraints:** Use ESM imports with `.js` extensions. Import `NomosError` from `../errors.js`. Import types from `../../types/index.js`. Use `fs/promises` for file I/O.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export const ProjectMapSchema' src/core/graph/map-schema.ts` — exactly 1 match. Run `grep 'export function migrateProjectMap' src/core/graph/map-schema.ts` — exactly 1 match. Run `grep 'export async function readProjectMap' src/core/graph/map-schema.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/map-schema.ts` and retry.
+
+#### Step 1.4: Implement `FileScanner`
+- **Target File:** `src/core/graph/scanner.ts` (new file)
+- **Action:** Create a `FileScanner` class with:
+  1. Constructor: `(projectRoot: string, config: NomosConfig['graph'], logger: Logger)`
+  2. `LANGUAGE_MAP` constant: maps file extensions (`.ts`, `.tsx`, `.mts`, `.cts`, `.d.ts`, `.js`, `.mjs`, `.cjs`, `.jsx`, `.py`, `.go`, `.rs`) to language strings. Defined as module-level constant.
+  3. `scan(existingMap: ProjectMap | null, force: boolean, globPatterns?: string[]): Promise<ScanResult>` where `ScanResult = { files: Map<string, { file: string; hash: string; language: string; content: string }>; carried: Map<string, FileNode> }`.
+  4. Logic:
+     a. Read `.gitignore` at project root using `gitignore-parser`. If file missing, use empty ignore list.
+     b. Use `fast-glob` with patterns `**/*` (or user-provided globs), applying both gitignore patterns and `config.exclude_patterns` as `ignore` option.
+     c. For each matched file: check extension against `LANGUAGE_MAP` — skip if unknown. Compute `sha256:<hex>` hash using `node:crypto`. If file unreadable (`EACCES`, `ENOENT`), log warning and skip.
+     d. If `existingMap` is not null and `force` is false: compare hash. If unchanged, add to `carried` map (existing `FileNode` carried forward). Otherwise add to `files` map (needs parsing).
+     e. If `existingMap` is null or `force` is true: add all to `files` map.
+- **Constraints:** Do not import `tree-sitter`. Do not perform AST parsing. Export `LANGUAGE_MAP` for use by other modules. All file paths must be relative to project root.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class FileScanner' src/core/graph/scanner.ts` — exactly 1 match. Run `grep 'LANGUAGE_MAP' src/core/graph/scanner.ts` — at least 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/scanner.ts` and retry.
+
+#### Step 1.5: Test `FileScanner`
+- **Target File:** `src/core/graph/__tests__/scanner.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Finds `.ts` and `.js` files in a temporary 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 (e.g., `.png`).
+  7. Carries forward unchanged `FileNode` from existing map when `force=false`.
+  8. Re-scans all files when `force=true` even if hashes match.
+- **Constraints:** Use `vitest` (`describe`, `it`, `expect`). Create temporary fixture files using `fs/promises` in a `beforeEach` / `afterEach` with `os.tmpdir()`. Mock the logger with `{ warn: vi.fn(), info: vi.fn(), error: vi.fn(), debug: vi.fn() }`.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/scanner.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests. If fundamentally broken, delete test file and re-evaluate Step 1.4.
+
+---
+
+### Phase 2: AST Parsing & Symbol Extraction
+**Dependencies:** Phase 1 complete (Steps 1.1–1.5 verified).
+
+#### Step 2.1: Implement `ASTParser` — grammar selection + symbol extraction
+- **Target File:** `src/core/graph/parser.ts` (new file)
+- **Action:** Create an `ASTParser` class with:
+  1. Constructor: `(logger: Logger)` — initializes `tree-sitter` `Parser` instance.
+  2. `parse(filePath: string, content: string, language: string): ParseResult` where `ParseResult = { symbols: SymbolEntry[]; imports: ImportEntry[] }`.
+  3. Grammar selection: Use `tree-sitter-typescript`'s `tsx` grammar for `.tsx` files; `typescript` grammar for all other TS variants. Use `javascript` grammar for JS files. For unsupported languages (`python`, `go`, `rust`), return empty `symbols` and `imports` with a debug log (Phase 1 only supports TS/JS).
+  4. Error-node threshold: After parsing, count total character length of all `ERROR` nodes. If `errorChars / totalChars > 0.20`, log `[nomos:graph:warn] Parse errors in {filePath} — symbols may be incomplete` and return empty symbols + imports.
+  5. Symbol extraction via tree walk:
+     - `function_declaration`, `arrow_function` (when parent is `variable_declarator` or `export_statement`) → `kind: 'function'`
+     - `class_declaration` → `kind: 'class'`; walk child `method_definition` nodes → `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. For each symbol: extract `line` (1-indexed from `node.startPosition.row + 1`), `end_line` (`node.endPosition.row + 1`), `exported` (parent or grandparent is `export_statement`).
+  7. Signature capture: For functions, extract text from name through closing `)` of params + return type annotation. For methods, include `async`/access modifiers.
+- **Constraints:** Import `tree-sitter` and `tree-sitter-typescript` as external ESM modules. Do not parse imports in this step — that is Step 2.2.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class ASTParser' src/core/graph/parser.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/parser.ts` and retry.
+
+#### Step 2.2: Implement import extraction in `ASTParser`
+- **Target File:** `src/core/graph/parser.ts` (modify existing)
+- **Action:** In the `parse()` method's tree walk, add extraction of:
+  1. `import_statement` nodes: extract `source` from the string literal child, extract `symbols` from named import specifiers (e.g., `{ z, ZodSchema }` → `['z', 'ZodSchema']`). Default/namespace imports record an empty `symbols` array.
+  2. `call_expression` with callee name `require`: extract `source` from the first argument string literal.
+  3. For each extracted import: create `ImportEntry` with `source`, `symbols`, `resolved: null` (filled by Phase 3 resolver), `is_external: false` (tentative — resolver will correct this).
+- **Constraints:** Only modify the `parse()` method. Do not resolve import paths — leave `resolved: null`.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'import_statement' src/core/graph/parser.ts` — at least 1 match.
+- **Rollback/Failure Action:** Revert changes to `src/core/graph/parser.ts` (keep Step 2.1 work intact).
+
+#### Step 2.3: Test `ASTParser`
+- **Target File:** `src/core/graph/__tests__/parser.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Extracts function declarations (name, line, end_line, exported flag, signature).
+  2. Extracts class declarations and their methods as `kind: 'method'` with `ClassName.methodName` naming.
+  3. Extracts interface, type, and enum declarations.
+  4. Extracts `export const` variable declarations.
+  5. Selects `tsx` grammar for `.tsx` extension — test with JSX content.
+  6. Error-node threshold: feed malformed TypeScript content (> 20% errors) → returns empty arrays.
+  7. Extracts import statements with named symbols.
+  8. Extracts `require()` calls.
+  9. Import `resolved` field is always `null`.
+- **Constraints:** Use inline TypeScript strings as test input (no fixture files needed). Create a real `ASTParser` instance (tree-sitter is a real dependency, not mocked).
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/parser.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests. If tree-sitter loading fails, verify Step 0.2 externals configuration.
+
+---
+
+### Phase 3: Import Resolution & Dependency Graph
+**Dependencies:** Phase 2 complete (Steps 2.1–2.3 verified).
+
+#### Step 3.1: Implement `ImportResolver`
+- **Target File:** `src/core/graph/resolver.ts` (new file)
+- **Action:** Create an `ImportResolver` class with:
+  1. Constructor: `(projectRoot: string, logger: Logger)` — reads `tsconfig.json` from project root to extract `compilerOptions.paths`. If `tsconfig.json` missing or has no `paths`, stores empty alias map.
+  2. `resolve(importSource: string, importerFile: string, knownFiles: Set<string>): ResolveResult` where `ResolveResult = { resolved: string | null; is_external: boolean }`.
+  3. Resolution logic (in order):
+     a. **External check:** If `importSource` does not start with `.`, `/`, or a matched tsconfig alias prefix → `{ resolved: null, is_external: true }`.
+     b. **Tsconfig alias resolution:** Match `importSource` against `compilerOptions.paths` keys (supporting `*` wildcard). On match, substitute the capture into the first value pattern, then continue to relative resolution below.
+     c. **Relative path resolution:** Compute absolute path from `importerFile`'s directory. Try extensions in order: `.ts`, `.tsx`, `.js`. Then try `/index.ts`, `/index.tsx`, `/index.js`. Check each against `knownFiles` set (relative paths). First match wins → `{ resolved: matchedRelativePath, is_external: false }`.
+     d. **Path traversal guard:** If resolved absolute path falls outside `projectRoot`, log warning → `{ resolved: null, is_external: true }`.
+     e. **Unresolvable:** Log `[nomos:graph:warn] Cannot resolve import '{importSource}' from '{importerFile}'` → `{ resolved: null, is_external: false }`.
+- **Constraints:** Do not use any external package — pure Node.js path manipulation + `fs.existsSync` for alias resolution file checks. All returned paths must be relative to project root using forward slashes.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class ImportResolver' src/core/graph/resolver.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/resolver.ts` and retry.
+
+#### Step 3.2: Implement `GraphBuilder`
+- **Target File:** `src/core/graph/builder.ts` (new file)
+- **Action:** Create a `GraphBuilder` class with:
+  1. Constructor: `(config: NomosConfig['graph'], logger: Logger)`
+  2. `build(fileNodes: Map<string, FileNode>): void` — mutates `FileNode` objects in-place to populate `dependencies`, `dependents`, and `depth` fields, and returns the `stats` object.
+  3. Logic:
+     a. **Adjacency list:** For each file, iterate its `imports[]`. For each import with `resolved !== null` and `is_external === false`: add `resolved` to the file's `dependencies[]`; add the file to the resolved target's `dependents[]`.
+     b. **Kahn's BFS topological sort:**
+        - Compute in-degree for each node = `dependents.length` (after populating dependents).
+        - Initialize queue with all nodes having in-degree 0 → assign `depth = 0`.
+        - BFS: for each dequeued node, decrement in-degree of all its dependents; if in-degree reaches 0, enqueue and assign `depth = currentDepth + 1`.
+     c. **Cycle detection:** After BFS, any node with remaining in-degree > 0 is in a cycle. Find the max depth among nodes that have edges entering the cycle, assign cyclic nodes `depth = maxDepth + 1`. Log: `[nomos:graph:warn] Circular dependency detected: {cycle path}`.
+     d. **Stats:** `total_files`, `total_symbols` (sum of all `symbols.length`), `total_edges` (count of non-external resolved imports), `core_modules` (top N files sorted by `depth` descending, N = `config.core_modules_count`).
+  4. Return type: `{ total_files: number; total_symbols: number; total_edges: number; core_modules: string[] }`.
+- **Constraints:** Mutate `FileNode` objects in-place (they are already in the map). Do not clone. `dependencies` and `dependents` arrays must be deduped (use `Set` during construction, convert to array at end).
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class GraphBuilder' src/core/graph/builder.ts` — exactly 1 match. Run `grep 'Kahn' src/core/graph/builder.ts` — at least 1 match (in comment).
+- **Rollback/Failure Action:** Delete `src/core/graph/builder.ts` and retry.
+
+#### Step 3.3: Test `ImportResolver`
+- **Target File:** `src/core/graph/__tests__/resolver.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Resolves `./utils/hash` → `src/utils/hash.ts` (appends `.ts` extension).
+  2. Resolves `./utils` → `src/utils/index.ts` (index file resolution).
+  3. Resolves tsconfig alias `@/utils` → `src/utils/index.ts` (wildcard substitution).
+  4. Identifies `zod` as external (`is_external: true`, `resolved: null`).
+  5. Identifies `commander` as external.
+  6. Path traversal: `../../outside-project` → treated as external with warning.
+  7. Unresolvable relative import → `resolved: null`, `is_external: false`.
+  8. Missing `tsconfig.json` → alias resolution skipped gracefully.
+- **Constraints:** Use a temporary fixture directory with actual files for resolution checks. Mock the logger.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/resolver.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests or re-evaluate Step 3.1 logic.
+
+#### Step 3.4: Test `GraphBuilder`
+- **Target File:** `src/core/graph/__tests__/builder.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Simple chain: A imports B, B imports C → depths: A=0, B=1, C=2.
+  2. Fan-in: A imports C, B imports C → C has highest depth, A and B are depth 0.
+  3. Forward/reverse edges: `A.dependencies` includes `B.file`, `B.dependents` includes `A.file`.
+  4. 2-node cycle: A imports B, B imports A → both assigned `depth = max + 1`, warning logged.
+  5. 3-node cycle: A→B→C→A → all three assigned cycle depth, warning logged.
+  6. `core_modules` extraction: returns top N files by depth.
+  7. Stats: `total_files`, `total_symbols`, `total_edges` are correct.
+- **Constraints:** Create `FileNode` objects directly in test code (no disk I/O needed). Mock the logger.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/builder.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests or re-evaluate Step 3.2 logic.
+
+---
+
+### Phase 4: AI Semantic Enrichment
+**Dependencies:** Phase 3 complete (Steps 3.1–3.4 verified).
+
+#### Step 4.1: Implement `SemanticEnricher`
+- **Target File:** `src/core/graph/enricher.ts` (new file)
+- **Action:** Create a `SemanticEnricher` class with:
+  1. Constructor: `(config: NomosConfig['graph'], logger: Logger)` — validates `process.env.GEMINI_API_KEY` exists; if absent and `config.ai_enrichment` is true, throws `NomosError('graph_ai_key_missing', 'GEMINI_API_KEY environment variable is not set.')`. Initializes `GoogleGenerativeAI` client and `p-limit` limiter with `config.ai_concurrency`.
+  2. `enrich(fileNodes: Map<string, FileNode>): Promise<void>` — mutates `FileNode.semantic` in-place.
+  3. Logic per file:
+     a. **Staleness check:** Skip if `semantic !== null` AND `semantic.source_hash === hash`.
+     b. **Prompt construction:** Truncate file content at last complete line boundary before `config.max_file_chars` characters. Build prompt per task spec format: File, Language, Exports, Used by, file content, JSON schema instruction.
+     c. **Gemini API call:** Use `model.generateContent()` with `generationConfig.responseSchema` for structured JSON output.
+     d. **Rate limiting:** Use `p-limit` for concurrency. Enforce minimum inter-request gap of `Math.ceil(60000 / config.ai_requests_per_minute)` ms using a timestamp tracker.
+     e. **Retry policy:** On HTTP 429 or 503, retry up to 3 times with exponential backoff (2s, 4s, 8s). After 3 failures, set `semantic: null` and log error.
+     f. **Zod validation:** Validate Gemini response against `SemanticInfoSchema` (from `map-schema.ts`). If validation fails, log raw response (truncated to 200 chars), set `semantic: null`.
+     g. **Populate `SemanticInfo`:** `{ overview, purpose, key_logic, usage_context, source_hash: fileNode.hash, enriched_at: new Date().toISOString(), model: config.ai_model }`.
+- **Constraints:** Never throw on a per-file failure — only log and set `semantic: null`. The only throw is in constructor for missing API key.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class SemanticEnricher' src/core/graph/enricher.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/enricher.ts` and retry.
+
+#### Step 4.2: Implement `ContractWriter`
+- **Target File:** `src/core/graph/contract-writer.ts` (new file)
+- **Action:** Create a `ContractWriter` class with:
+  1. Constructor: `(projectRoot: string, logger: Logger)`
+  2. `writeContracts(fileNodes: Map<string, FileNode>): Promise<void>`
+  3. Logic per file:
+     a. Skip if `semantic === null`.
+     b. Compute output path: replace source extension with `.semantic.md` (e.g., `src/core/state.ts` → `src/core/state.semantic.md`).
+     c. **Overwrite skip:** If `.semantic.md` file already exists, read its content and check if it contains the current `source_hash`. If hash matches, skip writing.
+     d. Write markdown using the template from the task spec:
+        ```markdown
+        # {filename} — Semantic Contract
+        > Auto-generated by `arc map` — do not edit manually.
+
+        ## Overview
+        {overview}
+
+        ## Purpose
+        {purpose}
+
+        ## Key Logic
+        1. {key_logic[0]}
+        2. {key_logic[1]}
+        ...
+
+        ## Usage Context
+        Used by: {dependents}
+        - {usage_context[0]}
+        - {usage_context[1]}
+        ...
+
+        ---
+        *Enriched at: {enriched_at} | Model: {model}*
+        ```
+- **Constraints:** Use `fs/promises`. Do not create directories — source files already exist so their parent directories exist. Log each write at debug level.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class ContractWriter' src/core/graph/contract-writer.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/contract-writer.ts` and retry.
+
+#### Step 4.3: Test `SemanticEnricher`
+- **Target File:** `src/core/graph/__tests__/enricher.test.ts` (new file)
+- **Action:** Write vitest tests with `vi.mock('@google/generative-ai')` covering:
+  1. Enriches a file with null semantic — mock returns valid JSON → `semantic` populated.
+  2. Staleness check: file with matching `source_hash` → skipped (no API call).
+  3. Zod validation failure: mock returns `{ overview: 123 }` (wrong type) → `semantic: null`.
+  4. Retry on 429: mock throws 429 twice then succeeds → `semantic` populated.
+  5. Key missing: `GEMINI_API_KEY` unset → constructor throws `NomosError('graph_ai_key_missing')`.
+  6. All retries exhausted: mock throws 429 four times → `semantic: null`, error logged.
+- **Constraints:** Mock `@google/generative-ai` at module level with `vi.mock()`. Save/restore `process.env.GEMINI_API_KEY` in `beforeEach`/`afterEach`.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/enricher.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests or re-evaluate Step 4.1.
+
+#### Step 4.4: Test `ContractWriter`
+- **Target File:** `src/core/graph/__tests__/contract-writer.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Writes `.semantic.md` with correct markdown structure and all four sections.
+  2. Skips writing when `source_hash` in existing `.semantic.md` matches current hash.
+  3. Overwrites when hash has changed.
+  4. Skips files with `semantic: null`.
+- **Constraints:** Use temporary directory for output. Verify file contents with `fs/promises.readFile`.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/contract-writer.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests or re-evaluate Step 4.2.
+
+---
+
+### Phase 5: Command, Pipeline, and Integration
+**Dependencies:** Phase 4 complete (Steps 4.1–4.4 verified).
+
+#### Step 5.1: Implement `MapPipeline`
+- **Target File:** `src/core/graph/pipeline.ts` (new file)
+- **Action:** Create a `MapPipeline` class that chains all phases:
+  1. Constructor: `(config: NomosConfig, projectRoot: string, logger: Logger)`
+  2. `run(options: { noAi: boolean; force: boolean; patterns?: string[] }): Promise<{ map: ProjectMap; aiFailures: number }>` — the main execution method.
+  3. Pipeline flow:
+     a. Read existing `project_map.json` via `readProjectMap()` (returns null if missing).
+     b. Call `FileScanner.scan()` → get `files` (need parsing) and `carried` (unchanged).
+     c. If `files` is empty and `carried` is empty: log warning `No files matched`, return early with empty map.
+     d. For each file in `files`: call `ASTParser.parse()` → build `FileNode` with `symbols`, `imports`, `hash`, `language`, `last_parsed_at: new Date().toISOString()`.
+     e. Merge parsed `FileNode` objects with `carried` `FileNode` objects into a single `Map<string, FileNode>`.
+     f. Initialize `ImportResolver`, call `resolve()` for every `ImportEntry` in every `FileNode` → populate `resolved` and `is_external`.
+     g. Call `GraphBuilder.build()` → mutates `dependencies`, `dependents`, `depth` → returns `stats`.
+     h. If `noAi` is false: call `SemanticEnricher.enrich()` → mutates `semantic` fields. Then call `ContractWriter.writeContracts()`.
+     i. Construct `ProjectMap` object with `schema_version: 1`, `generated_at`, `root`, `files`, `stats`.
+     j. Atomic write to `{config.graph.output_dir}/project_map.json` using `tmp → fsync → rename` pattern. Create output directory with `fs.mkdir(outDir, { recursive: true })` first. On write failure, throw `NomosError('graph_write_failed', ...)`.
+     k. Count AI failures (files with `semantic: null` that were attempted) and return.
+- **Constraints:** Do not duplicate atomic write logic from `state.ts` — implement it inline following the same pattern. The pipeline must not throw on partial AI failures — only on I/O failures.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class MapPipeline' src/core/graph/pipeline.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/pipeline.ts` and retry.
+
+#### Step 5.2: Implement `arc map` command
+- **Target File:** `src/commands/map.ts` (new file)
+- **Action:** Create a `registerMapCommand(program: Command): void` function that registers `arc map`:
+  1. Options: `--no-ai` (boolean flag), `--force` (boolean flag), variadic `[patterns...]` argument.
+  2. Action handler:
+     a. Load config via `loadConfig()`.
+     b. If `--no-ai` is set, override `config.graph.ai_enrichment = false`.
+     c. Create `MapPipeline` and call `run()`.
+     d. Print summary to stdout: `Mapped {N} files, enriched {M}, {K} skipped`.
+     e. Exit codes: `0` on full success, `1` on fatal error (catch `NomosError`), `2` if `aiFailures > 0` but map was written.
+  3. Progress output to stderr: files scanned count, AI per-file status.
+- **Constraints:** Follow the same pattern as existing commands in `src/commands/`. Import `loadConfig` from `../core/config.js`. Use `process.stderr.write()` for progress, `console.log()` for final summary.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'registerMapCommand' src/commands/map.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/commands/map.ts` and retry.
+
+#### Step 5.3: Register `arc map` in CLI entry point
+- **Target File:** `src/cli.ts` (modify existing)
+- **Action:**
+  1. Add import: `import { registerMapCommand } from './commands/map.js';`
+  2. Add `registerMapCommand` to the command registration array (the `[...].forEach(fn => fn(program))` block).
+- **Constraints:** Do not modify any other imports or registrations. Place the import alphabetically among existing command imports.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'registerMapCommand' src/cli.ts` — exactly 2 matches (import + usage). Run `npx tsx src/cli.ts map --help` — shows help text for `arc map` with `--no-ai` and `--force` options.
+- **Rollback/Failure Action:** Revert `src/cli.ts` changes.
+
+#### Step 5.4a: Extend `PromptOptions` with `architecturalConstraints`
+- **Target File:** `src/types/index.ts`
+- **Action:** Add `architecturalConstraints: string | null;` property to the `PromptOptions` interface, after the `mode` field.
+- **Constraints:** Do not modify any other field. Add a comment: `// Injected from project_map.json by arc map`.
+- **Verification Criteria:** Run `npx tsc --noEmit` — will show errors in files that construct `PromptOptions` without the new field. This is expected — Step 5.4c will fix them. Verify with `grep 'architecturalConstraints' src/types/index.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Remove the added line.
+
+#### Step 5.4b: Implement `readArchitecturalConstraints`
+- **Target File:** `src/core/graph/constraints.ts` (new file)
+- **Action:** Create and export `readArchitecturalConstraints(projectRoot: string, outputDir: string, contextFiles: string[]): Promise<string | null>`:
+  1. Read `project_map.json` from `path.join(projectRoot, outputDir, 'project_map.json')`. If file does not exist, return `null`.
+  2. Parse with `migrateProjectMap()`.
+  3. For each `contextFile`:
+     a. Look up in `map.files`. If absent, log `[nomos:graph:warn] {file} not in project map — run arc map to update` and skip.
+     b. For each found `FileNode`, collect `dependents[]` that have non-null `semantic`.
+     c. For each dependent, identify which `symbols[]` from the context file they consume (by checking the dependent's `imports[].symbols` where `imports[].resolved` matches the context file).
+  4. Build constraint string with format:
+     ```
+     - {contextFile} → symbol: {signature}
+       Consumed by: {dependent1}, {dependent2}
+       Contract: "{semantic.purpose or overview from dependent}"
+     ```
+  5. Return the assembled string, or `null` if no constraints found.
+- **Constraints:** Import `readProjectMap` and `migrateProjectMap` from `./map-schema.js`. Do not read `.semantic.md` files — all data comes from `project_map.json`.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0 (assuming 5.4a is done). Run `grep 'readArchitecturalConstraints' src/core/graph/constraints.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/constraints.ts` and retry.
+
+#### Step 5.4c: Wire constraints into `Orchestrator.plan()` and `assemblePrompt()`
+- **Target Files:** `src/core/orchestrator.ts`, `src/core/prompt.ts`
+- **Action:**
+  1. In `src/core/prompt.ts` → `assemblePrompt()` function: After the existing sections, add:
+     ```typescript
+     if (options.architecturalConstraints !== null) {
+       sections.push(
+         `[ARCHITECTURAL CONSTRAINTS]\n` +
+         `The following contracts MUST NOT be broken. Changing the listed symbol signatures ` +
+         `or return types will break dependent modules.\n\n` +
+         options.architecturalConstraints
+       );
+     }
+     ```
+  2. In `src/core/orchestrator.ts` → `plan()` method: Before the call to `assemblePrompt(...)`:
+     a. Import `readArchitecturalConstraints` from `./graph/constraints.js`.
+     b. Call `const constraints = await readArchitecturalConstraints(this.projectRoot, this.config.graph.output_dir, contextFiles)`.
+     c. Pass `architecturalConstraints: constraints` into the `PromptOptions` object.
+  3. Fix any other call sites that construct `PromptOptions` to include `architecturalConstraints: null` (check for compilation errors).
+- **Constraints:** Do not modify the `ReviewPromptOptions` interface or `assembleReviewPrompt()`. The `[ARCHITECTURAL CONSTRAINTS]` section must appear AFTER all other sections in the prompt.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `npx vitest run` — all existing tests pass (may need to update test fixtures that construct `PromptOptions` to include the new field as `null`). Run `grep 'ARCHITECTURAL CONSTRAINTS' src/core/prompt.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Revert changes to both files.
+
+#### Step 5.5: Test `MapPipeline` end-to-end
+- **Target File:** `src/core/graph/__tests__/pipeline.test.ts` (new file)
+- **Precondition:** Create the test fixture directory `test/fixtures/sample-project/` with these files BEFORE writing the test:
+
+**Sub-step 5.5a: Create test fixture**
+- **Target Directory:** `test/fixtures/sample-project/`
+- **Action:** Create the following files:
+  - `tsconfig.json`: `{ "compilerOptions": { "paths": { "@/utils": ["src/utils/index.ts"] } } }`
+  - `src/types.ts`: exports `interface User { name: string }` and `type UserId = string`
+  - `src/utils/index.ts`: exports `function hash(s: string): string { return s; }` — imports nothing
+  - `src/utils/format.ts`: exports `function formatUser(u: User): string { return u.name; }` — imports `../types` and `@/utils`
+  - `src/service.ts`: exports `class UserService { getUser(id: UserId): User { return { name: '' }; } }` — imports `./types` and `./utils/index`
+  - `src/main.ts`: imports `./service` — no exports (entry point)
+  - `src/circular-a.ts`: exports `const a = 1;` — imports `./circular-b`
+  - `src/circular-b.ts`: exports `const b = 2;` — imports `./circular-a`
+- **Verification Criteria:** Run `ls test/fixtures/sample-project/src/` — shows 6 `.ts` files + `utils/` directory.
+
+**Sub-step 5.5b: Write pipeline tests**
+- **Target File:** `src/core/graph/__tests__/pipeline.test.ts`
+- **Action:** Write vitest tests covering:
+  1. Full pipeline on `test/fixtures/sample-project/` with `noAi: true` → produces `project_map.json` with correct file count (8 files).
+  2. `src/types.ts` and `src/utils/index.ts` have the highest depth values.
+  3. `src/main.ts` has depth 0.
+  4. `circular-a.ts` and `circular-b.ts` are detected as a cycle (warning logged).
+  5. Incremental run: run pipeline twice without changes → second run carries forward all nodes (0 files re-parsed).
+  6. `--force` flag: run pipeline twice with force=true → all files re-parsed on second run.
+  7. `stats.core_modules` contains the expected high-depth files.
+  8. `stats.total_edges` counts only internal resolved imports.
+- **Constraints:** Use `noAi: true` for all tests (avoid needing Gemini API key in CI). Write `project_map.json` to a temp directory, not the fixture itself.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/pipeline.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests or trace issue back to the specific phase component.
+
+#### Step 5.6: Test Architectural Constraint injection
+- **Target File:** `src/core/__tests__/prompt.test.ts` (modify existing)
+- **Action:** Add new test cases:
+  1. When `architecturalConstraints` is a non-null string → `assemblePrompt()` output contains `[ARCHITECTURAL CONSTRAINTS]` section with the exact constraint text.
+  2. When `architecturalConstraints` is `null` → `assemblePrompt()` output does NOT contain `[ARCHITECTURAL CONSTRAINTS]`.
+  3. Integration: write a minimal `project_map.json` to a temp directory with known symbols, call `readArchitecturalConstraints()` → verify constraint string mentions the expected symbol signatures.
+  4. Missing-from-map file: call `readArchitecturalConstraints()` with a `contextFiles` entry that does not exist in the map → warning logged, file skipped gracefully.
+- **Constraints:** Update any existing test fixtures that construct `PromptOptions` to include `architecturalConstraints: null`.
+- **Verification Criteria:** Run `npx vitest run src/core/__tests__/prompt.test.ts` — all tests pass (both new and existing), exit code 0.
+- **Rollback/Failure Action:** Fix failing tests.
+
+---
+
+### Phase 6: Visualization — `arc show map`
+**Dependencies:** Phase 5 complete (Steps 5.1–5.6 verified).
+
+#### Step 6.1: Implement `MapRenderer`
+- **Target File:** `src/core/graph/renderer.ts` (new file)
+- **Action:** Create a `MapRenderer` class with:
+  1. `render(map: ProjectMap): { nodes: CytoscapeNode[]; edges: CytoscapeEdge[] }` — transforms `ProjectMap` into Cytoscape.js format.
+  2. Each `FileNode` → node: `{ data: { id: relativePath, label: filename, ...fullFileNode } }`.
+  3. Each dependency link → edge: `{ data: { source: importerPath, target: dependencyPath } }`.
+  4. `computeColor(depth: number, maxDepth: number): string` — maps depth to hex color gradient:
+     - Depth 0: `#a8d8ea` (cool blue)
+     - Mid depth: `#f9c784` (warm amber)
+     - Max depth: `#c0392b` (deep red)
+     - Interpolate linearly between these three stops.
+- **Constraints:** Export `CytoscapeNode` and `CytoscapeEdge` types. Do not import Cytoscape.js — the renderer produces plain JSON that the HTML template consumes.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'export class MapRenderer' src/core/graph/renderer.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/renderer.ts` and retry.
+
+#### Step 6.2a: Create HTML template — static shell with BFS layout
+- **Target File:** `src/core/graph/html-template.ts` (new file)
+- **Action:** Create an `export function generateHtml(mapJson: string, cytoscapeNodes: string, cytoscapeEdges: string): string` that returns a complete HTML document string:
+  1. `<!DOCTYPE html>` with `<meta charset="utf-8">`.
+  2. `<script src="https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.28.1/cytoscape.min.js"></script>` — pinned CDN.
+  3. Inline `<style>` for full-viewport layout: `body { margin: 0; } #cy { width: 100%; height: 100vh; }`.
+  4. `<div id="cy"></div>` container.
+  5. Inline `<script>`:
+     - `const PROJECT_MAP = ${mapJson};`
+     - Initialize Cytoscape with BFS layout: `layout: { name: 'breadthfirst', directed: true, roots: coreModules }`.
+     - Apply node colors from embedded data.
+     - Style: `node { label: data(label), background-color: data(color), ... }; edge { target-arrow-shape: triangle, curve-style: bezier }`.
+- **Constraints:** The HTML must be completely self-contained — no external files other than the pinned Cytoscape CDN. Template literal must properly escape embedded JSON.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'cytoscape/3.28.1' src/core/graph/html-template.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/core/graph/html-template.ts` and retry.
+
+#### Step 6.2b: Add context card panel to HTML template
+- **Target File:** `src/core/graph/html-template.ts` (modify existing)
+- **Action:** Add to the HTML template:
+  1. A `<div id="info-panel">` fixed to the right side, 320px wide, hidden by default.
+  2. CSS: `#info-panel { position: fixed; right: 0; top: 0; width: 320px; height: 100vh; overflow-y: auto; background: #fff; box-shadow: -2px 0 8px rgba(0,0,0,0.1); padding: 16px; display: none; }`.
+  3. JavaScript: On node click (`cy.on('tap', 'node', ...)`), populate the panel with:
+     - Filename + language badge.
+     - `semantic.overview` and `semantic.purpose` (or "Run `arc map` to enrich" if null).
+     - `dependents[]` list as `<a>` elements that re-center the graph on the clicked dependent.
+     - `symbols[]` list with kind badges and signatures.
+  4. Show panel on node click, hide on canvas click.
+- **Constraints:** Modify only the template string content. Do not change the function signature.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'info-panel' src/core/graph/html-template.ts` — at least 1 match.
+- **Rollback/Failure Action:** Revert to Step 6.2a state and retry.
+
+#### Step 6.2c: Add ripple analysis to HTML template
+- **Target File:** `src/core/graph/html-template.ts` (modify existing)
+- **Action:** Add to the node click handler:
+  1. On node click: find all direct dependents (`node.data('dependents')`) → highlight in red (`#e74c3c`).
+  2. Find transitive dependents (dependents of dependents, BFS traversal) → highlight in yellow (`#f39c12`).
+  3. Dim all other nodes to grey (`#bdc3c7`).
+  4. Clicked node keeps its original color but gets a border highlight.
+  5. On canvas click (`cy.on('tap', function(evt) { if (evt.target === cy) ... })`): reset all nodes to their default depth-based colors.
+- **Constraints:** BFS traversal must use the `dependents` data field, not Cytoscape graph traversal (to match the task spec's direction: dependents = files that import this node).
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'e74c3c' src/core/graph/html-template.ts` — at least 1 match (red color). Run `grep 'f39c12' src/core/graph/html-template.ts` — at least 1 match (yellow color).
+- **Rollback/Failure Action:** Revert ripple analysis code only, keep Steps 6.2a and 6.2b intact.
+
+#### Step 6.2d: Add symbol search bar to HTML template
+- **Target File:** `src/core/graph/html-template.ts` (modify existing)
+- **Action:** Add to the HTML template:
+  1. A `<div id="search-bar">` at the top of the page: `<input type="text" id="search-input" placeholder="Search symbols or files..." />`.
+  2. CSS: fixed position, top: 0, left: 0, width: `calc(100% - 320px)`, z-index above graph.
+  3. JavaScript: On input change (debounced 200ms):
+     a. Match input against all `FileNode.symbols[].name` and `FileNode.file` strings (case-insensitive substring).
+     b. Highlight matched nodes in green (`#27ae60`).
+     c. For each matched node, trace the full dependency chain (all importers recursively) and highlight those in lighter green.
+     d. Dim all other nodes to grey.
+  4. On Escape key or empty input: reset to default depth coloring.
+- **Constraints:** Debounce search to avoid lag on large graphs. Search is client-side against the embedded `PROJECT_MAP` data.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'search-input' src/core/graph/html-template.ts` — at least 1 match. Run `grep '27ae60' src/core/graph/html-template.ts` — at least 1 match (green color).
+- **Rollback/Failure Action:** Revert search bar code only, keep Steps 6.2a–6.2c intact.
+
+#### Step 6.3: Implement `arc show map` command
+- **Target File:** `src/commands/show.ts` (new file)
+- **Action:** Create a `registerShowCommand(program: Command): void` function:
+  1. Register a parent `show` command group: `program.command('show').description('Display visual outputs')`.
+  2. Register `map` subcommand: `.command('map').description('Open the interactive dependency graph in your browser')`.
+  3. Option: `--no-open` (boolean flag) — generate `index.html` without opening browser.
+  4. Action handler:
+     a. Load config via `loadConfig()`.
+     b. Read `project_map.json` via `readProjectMap()`. If null, print `[nomos:error] No project map found. Run: arc map first.` to stderr and exit 1.
+     c. Run `migrateProjectMap()` on loaded data.
+     d. Call `MapRenderer.render()` to get nodes/edges.
+     e. Call `generateHtml()` to produce the HTML string.
+     f. Write `index.html` to `{config.graph.output_dir}/index.html`.
+     g. If `--no-open` is not set: import `open` package and call `open(htmlPath)`.
+     h. Print path to stdout: `Graph visualization written to: {htmlPath}`.
+- **Constraints:** Use the `open` npm package for browser launch (not `child_process.exec`). Follow the same command registration pattern as existing commands.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'registerShowCommand' src/commands/show.ts` — exactly 1 match.
+- **Rollback/Failure Action:** Delete `src/commands/show.ts` and retry.
+
+#### Step 6.4: Register `arc show map` in CLI entry point
+- **Target File:** `src/cli.ts` (modify existing)
+- **Action:**
+  1. Add import: `import { registerShowCommand } from './commands/show.js';`
+  2. Add `registerShowCommand` to the command registration array.
+- **Constraints:** Do not modify any other imports or registrations.
+- **Verification Criteria:** Run `npx tsc --noEmit` — exit code 0. Run `grep 'registerShowCommand' src/cli.ts` — exactly 2 matches. Run `npx tsx src/cli.ts show map --help` — shows help text with `--no-open` option.
+- **Rollback/Failure Action:** Revert `src/cli.ts` changes.
+
+#### Step 6.5: Test `MapRenderer`
+- **Target File:** `src/core/graph/__tests__/renderer.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Correct node count matches `ProjectMap.files` count.
+  2. Correct edge count matches total internal dependency links.
+  3. Color at depth 0 = `#a8d8ea` (blue).
+  4. Color at max depth = `#c0392b` (red).
+  5. Color at mid depth is between blue and red (amber range).
+  6. Node data includes all `FileNode` fields.
+  7. Edge source/target match dependency relationships.
+  8. Empty map → 0 nodes, 0 edges (no crash).
+- **Constraints:** Create minimal `ProjectMap` objects directly in test code.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/renderer.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests.
+
+#### Step 6.6: Test `arc show map` command
+- **Target File:** `src/core/graph/__tests__/show.test.ts` (new file)
+- **Action:** Write vitest tests covering:
+  1. Map missing → function/command errors with `graph_map_not_found` or exits with code 1 and prints correct error message.
+  2. Map present → `index.html` is written to the correct output path.
+  3. Generated `index.html` contains `cytoscape/3.28.1` CDN link.
+  4. Generated `index.html` contains embedded `PROJECT_MAP` data.
+  5. `--no-open` flag: browser open function is NOT called (mock the `open` package with `vi.mock('open')`).
+- **Constraints:** Mock the `open` package. Use temp directories for output. Create a minimal valid `project_map.json` for test input.
+- **Verification Criteria:** Run `npx vitest run src/core/graph/__tests__/show.test.ts` — all tests pass, exit code 0.
+- **Rollback/Failure Action:** Fix failing tests.
+
+---
+
+## 4. Final System Integration & Validation
+
+### Full Test Suite
+- **Command:** `npx vitest run`
+- **Expected Output:** All tests pass — 0 failures. This includes all 9 new test files plus all existing tests.
+
+### Build Verification
+- **Command:** `npm run build`
+- **Expected Output:** `dist/cli.js` produced, exit code 0. The new `--external` flags prevent bundling of native modules.
+
+### Type Check
+- **Command:** `npx tsc --noEmit`
+- **Expected Output:** Exit code 0, no type errors.
+
+### End-to-End Smoke Test (Structural Only)
+- **Command:** `npx tsx src/cli.ts map --no-ai`
+- **Expected Output:** Map generated at `tasks-management/graph/project_map.json`. Summary printed to stdout: `Mapped N files, enriched 0, 0 skipped`. Exit code 0.
+- **Verification:** Run `cat tasks-management/graph/project_map.json | node -e "const m=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); console.log('files:', Object.keys(m.files).length, 'edges:', m.stats.total_edges)"` — prints file and edge counts.
+
+### Visualization Smoke Test
+- **Command:** `npx tsx src/cli.ts show map --no-open`
+- **Expected Output:** `Graph visualization written to: tasks-management/graph/index.html`. Exit code 0.
+- **Verification:** Run `grep 'cytoscape/3.28.1' tasks-management/graph/index.html` — match found.
+
+### Incremental Run Verification
+- **Command:** Run `npx tsx src/cli.ts map --no-ai` twice in succession.
+- **Expected Output:** Second run completes in under 1 second (all files carried forward, zero re-parsing). Summary indicates 0 files re-parsed.
+
+### File Inventory Check
+- **Expected new files (20 total):**
+  ```
+  src/core/graph/map-schema.ts
+  src/core/graph/scanner.ts
+  src/core/graph/parser.ts
+  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/__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/  (directory with 8 files)
+  ```
+- **Expected 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 section + PromptOptions field)
+  src/core/config.ts     (GraphConfigSchema)
+  src/core/prompt.ts     (architectural constraints section)
+  src/core/orchestrator.ts (constraint injection in plan())
+  src/cli.ts             (register map + show commands)
+  .gitignore             (semantic.md + graph dir)
+  ```
+- **Verification:** Run `git diff --stat HEAD` and verify only these files are modified/added.