@nomos-arc/arc 0.1.0

package/docs/map/semantic_graph_task.md

@@ -0,0 +1,792 @@
+# nomos-arc Semantic Graph — `arc map`
+
+## Architectural Master Plan
+
+Transform a raw codebase into a **Self-Aware Knowledge Base** by decoupling **Static Analysis** (fast, free) from **AI Enrichment** (cheap, batched). The result: `project_map.json` — a single artifact that both humans and AI agents consume.
+
+---
+
+## Design Principles
+
+1. **JSON is the source of truth** — consistent with the rest of nomos-arc (state, config, etc.). `.semantic.md` files are rendered views only; they are never parsed back by any code path.
+2. **Incremental by default** — SHA-256 file hashes mean we only re-analyze what changed.
+3. **AI is optional** — Phase 1-2 produce a fully usable structural map without spending a single AI token.
+4. **Fits existing patterns** — new command in `src/commands/map.ts`, core logic in `src/core/graph/`, types in `src/types/index.ts`.
+5. **Execution Rules compliance** — follows all 14 rules from the master plan: ESM imports, no shell injection, JSON source of truth, schema versioning with migration infrastructure, atomic writes.
+
+---
+
+## Data Model
+
+```typescript
+// ─── Semantic Graph Types ────────────────────────────────────────────────────
+
+interface FileNode {
+  file: string;              // relative path from project root (e.g. "src/core/state.ts")
+  hash: string;              // "sha256:<hex>" — skip re-analysis when unchanged
+  language: string;          // "typescript" | "javascript" | "python" | etc.
+  symbols: SymbolEntry[];    // classes, functions, exports extracted by parser
+  imports: ImportEntry[];    // resolved import references
+  dependents: string[];      // relative paths (matching FileNode keys) that import THIS file
+  dependencies: string[];    // relative paths (matching FileNode keys) that THIS file imports
+  depth: number;             // fan-in depth: 0 = nobody imports this file (entry point/leaf),
+                             // higher = more files depend on it (core module, high risk to modify)
+  last_parsed_at: string | null;  // ISO 8601 — when this node was last actively parsed
+                                  // null for carry-over nodes in incremental runs
+  semantic: SemanticInfo | null;  // null until AI enrichment runs
+}
+
+interface SymbolEntry {
+  name: string;              // "UserService", "handleAuth", etc.
+                             // for class methods: "ClassName.methodName"
+  kind: 'class' | 'function' | 'method' | 'interface' | 'type' | 'enum' | 'variable' | 'export';
+  line: number;              // start line (1-indexed)
+  end_line: number | null;   // end line (1-indexed), null if parser cannot determine
+  signature: string | null;  // "async handleAuth(req: Request): Promise<Response>"
+  exported: boolean;
+}
+
+interface ImportEntry {
+  source: string;            // raw import path ("./utils/hash", "zod", etc.)
+  resolved: string | null;   // canonical relative path from project root WITH extension
+                             // e.g. "src/utils/hash.ts" — always matches a FileNode key
+                             // null for external packages or unresolvable paths
+  symbols: string[];         // named imports ["z", "ZodSchema"]
+  is_external: boolean;
+}
+
+interface SemanticInfo {
+  overview: string;          // one-paragraph summary
+  purpose: string;           // business problem it solves
+  key_logic: string[];       // step-by-step algorithmic breakdown
+  usage_context: string[];   // how dependents use this file (from dependency data)
+  source_hash: string;       // "sha256:<hex>" of the file content at enrichment time
+                             // used for staleness check: re-enrich only when hash changes
+  enriched_at: string;       // ISO 8601 — when AI last analyzed this
+  model: string;             // which model produced this ("gemini-1.5-flash", etc.)
+}
+
+interface ProjectMap {
+  schema_version: 1;         // starts at 1; run migrateProjectMap() on read if older
+  generated_at: string;      // ISO 8601
+  root: string;              // absolute path of the project root — RUNTIME ONLY
+                             // not meaningful across machines; do not rely on for portability
+  files: Record<string, FileNode>;  // keyed by relative file path (matches FileNode.file)
+  stats: {
+    total_files: number;
+    total_symbols: number;
+    total_edges: number;     // count of internal (non-external) resolved dependency links only
+    core_modules: string[];  // top N files by depth — N = config.graph.core_modules_count
+  };
+}
+```
+
+### Depth Computation
+
+`depth` is computed by **BFS topological sort on the dependency graph** where an edge A → B means "A imports B":
+
+- In-degree of a node = number of files that import it (`dependents.length`)
+- **Depth 0**: nodes with in-degree 0 — entry points that no other file imports (e.g. `src/cli.ts`, `src/commands/plan.ts`)
+- **Depth N**: nodes that become reachable only after all their importers are processed
+- Core utilities (`src/types/index.ts`, `src/core/config.ts`) have the highest depth — many files depend on them
+
+Algorithm: Kahn's BFS. If cycles are detected, assign the highest depth among nodes entering the cycle + 1, log a warning, and continue.
+
+### ProjectMap Schema & Migrations
+
+Following Execution Rule 11, a Zod schema and migration infrastructure must exist from day one:
+
+```typescript
+// In src/core/graph/map-schema.ts
+import { z } from 'zod';
+
+const SymbolEntrySchema = z.object({ ... });
+const ImportEntrySchema = z.object({ ... });
+const SemanticInfoSchema = z.object({ ... });
+const FileNodeSchema = z.object({ ... });
+
+export const ProjectMapSchema = z.object({
+  schema_version: z.literal(1),
+  generated_at: z.string(),
+  root: z.string(),
+  files: z.record(z.string(), FileNodeSchema),
+  stats: z.object({
+    total_files: z.number(),
+    total_symbols: z.number(),
+    total_edges: z.number(),
+    core_modules: z.array(z.string()),
+  }),
+});
+
+// Migration map — empty now, infrastructure required from day one
+const migrations: Record<number, (raw: unknown) => unknown> = {};
+
+export function migrateProjectMap(raw: unknown): ProjectMap {
+  let current = raw as { schema_version?: number };
+  const version = current.schema_version ?? 0;
+  for (let v = version; v < 1; v++) {
+    const migrateFn = migrations[v];
+    if (migrateFn) current = migrateFn(current) as typeof current;
+  }
+  return ProjectMapSchema.parse(current) as ProjectMap;
+}
+```
+
+---
+
+## NomosConfig Extension
+
+Add to `NomosConfig` in `src/types/index.ts` and `GraphConfigSchema` in `src/core/config.ts`:
+
+```typescript
+// In NomosConfig interface (types/index.ts)
+graph: {
+  exclude_patterns: string[];     // glob patterns to exclude from scanning
+  ai_enrichment: boolean;         // default: true — set false for --no-ai behavior
+  ai_model: string;               // default: "gemini-1.5-flash"
+  ai_concurrency: number;         // default: 5 (max concurrent Gemini requests)
+  ai_requests_per_minute: number; // default: 14 (Gemini free tier: 15 RPM, leave headroom)
+  max_file_chars: number;         // default: 4000 — truncate at last complete line before limit
+  core_modules_count: number;     // default: 10 — top N files in stats.core_modules
+  output_dir: string;             // default: "tasks-management/graph"
+};
+```
+
+```typescript
+// In config.ts — GraphConfigSchema
+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'),
+});
+// Add to NomosConfigSchema: graph: GraphConfigSchema.default(() => GraphConfigSchema.parse({}))
+```
+
+---
+
+## New Error Codes
+
+Add to `NomosErrorCode` in `src/core/errors.ts`:
+
+```typescript
+| 'graph_map_not_found'     // project_map.json missing when arc show map runs
+| 'graph_parse_error'       // tree-sitter or file read failed for a file
+| 'graph_ai_key_missing'    // GEMINI_API_KEY not set when ai_enrichment is true
+| 'graph_write_failed'      // project_map.json atomic write failed
+```
+
+---
+
+## File Extension → Language Map
+
+```typescript
+const LANGUAGE_MAP: Record<string, string> = {
+  '.ts':  'typescript',
+  '.tsx': 'typescript',   // uses tsx grammar in tree-sitter-typescript
+  '.mts': 'typescript',
+  '.cts': 'typescript',
+  '.d.ts':'typescript',   // declaration files — symbols extracted but no imports
+  '.js':  'javascript',
+  '.mjs': 'javascript',
+  '.cjs': 'javascript',
+  '.jsx': 'javascript',
+  '.py':  'python',
+  '.go':  'go',
+  '.rs':  'rust',
+};
+// Files with unrecognized extensions are skipped (not an error).
+```
+
+---
+
+## Pipeline Overview
+
+```
+arc map [--no-ai] [--force] [glob patterns...]
+   |
+   v
+Phase 1: File Discovery & Hashing
+   |  fast-glob + gitignore-parser + node:crypto
+   v
+Phase 2: AST Parsing & Symbol Extraction
+   |  tree-sitter (ts/tsx/js) — external to esbuild bundle
+   v
+Phase 3: Import Resolution & Dependency Graph
+   |  custom resolver + Kahn's BFS topological sort
+   v
+Phase 4: AI Semantic Enrichment (skippable with --no-ai)
+   |  Gemini 1.5 Flash — p-limit(5), 4s inter-request gap, 3x retry
+   v
+Phase 5: Output
+   |  Atomic write project_map.json + .semantic.md files
+   v
+Phase 6: Visualization (arc show map)
+   |  Generate standalone index.html with Cytoscape.js
+   v
+Done — used by `arc plan` for Architectural Constraint injection
+```
+
+---
+
+## Phase 1: File Discovery & Hashing
+
+**Goal:** Find all source files and compute their SHA-256 hashes for incremental updates.
+
+**Input:** Project root + optional glob filters.
+**Output:** List of `{ file, hash, language }` entries.
+
+**How it works:**
+1. **First-run detection:** If `project_map.json` does not yet exist, treat all files as new (no hash matches — full parse required).
+2. **Gitignore parsing:** `fast-glob` does NOT natively respect `.gitignore`. Use the `gitignore-parser` package to read `.gitignore` at the project root, convert its patterns, and pass them to `fast-glob`'s `ignore` option alongside `config.graph.exclude_patterns`.
+3. **Hash each file:** Compute `sha256:<hex>` using `node:crypto`. If a file cannot be read (`EACCES`, `ENOENT`), log `[nomos:graph:warn] Cannot read {file} — skipping` and continue (do not throw).
+4. **Incremental skip:** Compare each file's hash against the existing `project_map.json`. If the hash matches AND `--force` is not set, carry the existing `FileNode` forward unchanged (mark `last_parsed_at` unchanged).
+5. **Language detection:** Use `LANGUAGE_MAP` above. Files with unknown extensions are skipped silently.
+
+**New dependencies:** `fast-glob`, `gitignore-parser`
+
+---
+
+## Phase 2: AST Parsing & Symbol Extraction
+
+**Goal:** Extract the structural skeleton — every class, function, interface, type, and export — without AI.
+
+**Input:** File content + language.
+**Output:** `symbols: SymbolEntry[]` + `imports: ImportEntry[]` per file.
+
+**How it works:**
+1. **Grammar selection:** `tree-sitter-typescript` ships two grammars. Use `tsx` grammar for `.tsx` files; use `typescript` grammar for all other TypeScript variants (`.ts`, `.mts`, `.cts`).
+2. **Error node handling:** If the parsed tree contains error nodes covering > 20% of the file (by character count), log `[nomos:graph:warn] Parse errors in {file} — symbols may be incomplete` and emit `symbols: []` and `imports: []` for that file. Do not fail the pipeline.
+3. **Symbol extraction:** Walk the tree to extract:
+   - Top-level function/arrow-function declarations (name, line, end_line, signature, exported)
+   - Class declarations (name, line, end_line, exported) + their method declarations as `kind: 'method'` with `name: 'ClassName.methodName'`
+   - Interface/type/enum declarations
+   - Top-level `export const` / `export let` variable declarations
+4. **Signature capture:** For functions, capture the full text span from the name through the closing `)` of the parameter list plus return type annotation. For class methods, include the `async` keyword and access modifier if present.
+5. **Import extraction:** During the same AST walk, extract all `import` declarations and `require()` calls. Populate `ImportEntry.source` with the raw module specifier; leave `resolved` as `null` for now (Phase 3 fills it).
+
+**esbuild note:** `tree-sitter` uses N-API native bindings (`.node` files) that cannot be bundled by esbuild. The `package.json` build script must include:
+```
+--external:tree-sitter --external:tree-sitter-typescript
+```
+
+**New dependencies:** `tree-sitter`, `tree-sitter-typescript`
+
+---
+
+## Phase 3: Import Resolution & Dependency Graph
+
+**Goal:** Map every `import`/`require` to its resolved file, then build a directed dependency graph.
+
+**Input:** `imports: ImportEntry[]` per file.
+**Output:** `dependencies[]`, `dependents[]`, `depth` per file + `stats.core_modules`.
+
+**How it works:**
+
+1. **Path resolution algorithm** (tried in this order for relative imports):
+   - Append `.ts`, `.tsx`, `.js` in that order and check existence
+   - Append `/index.ts`, `/index.tsx`, `/index.js` in that order
+   - If none resolve, set `resolved: null` (missing file — log warning, do not fail)
+
+2. **tsconfig alias resolution:**
+   - Read only `tsconfig.json` at the project root (no project references in Phase 1)
+   - Parse `compilerOptions.paths` — a `Record<string, string[]>` where keys may contain `*` wildcards
+   - Match import source against each key pattern in declaration order; on match, substitute the `*` capture into the corresponding value pattern, then apply the relative path resolution above
+   - Example: `"@/*": ["src/*"]` — import `@/core/state` → try `src/core/state.ts` etc.
+   - If `tsconfig.json` does not exist or has no `paths`, skip alias resolution
+
+3. **External packages:** Any import that does not start with `.`, `/`, or a matched tsconfig alias is `is_external: true`, `resolved: null`.
+
+4. **Path traversal guard:** If a resolved absolute path falls outside `projectRoot`, treat as external (`is_external: true`, `resolved: null`). Log `[nomos:graph:warn] Import escapes project root: {source}`.
+
+5. **Build adjacency list:**
+   - Forward edges: `A` imports `B` → `A.dependencies.push(B.file)`
+   - Reverse edges: → `B.dependents.push(A.file)`
+   - All values are relative paths matching `FileNode` keys
+
+6. **Topological sort (Kahn's BFS):**
+   - Compute in-degree for each node (`dependents.length`)
+   - BFS from all depth-0 nodes (in-degree 0 = nobody imports this file)
+   - Assign `depth` = BFS layer
+   - Extract `stats.core_modules` = top `config.graph.core_modules_count` files by depth
+
+7. **Cycle detection:** If Kahn's queue empties before all nodes are processed, remaining nodes form cycles. Assign them `depth = max_depth_of_cycle_entering_nodes + 1`. Log:
+   ```
+   [nomos:graph:warn] Circular dependency detected: src/a.ts → src/b.ts → src/a.ts
+   ```
+
+8. **Partial glob runs:** When `arc map "src/core/**"` is used, only matched files are scanned and their `dependencies[]` are updated. `dependents[]` back-references from unscanned files will be incomplete. The stats section will reflect only scanned files. Run `arc map` without patterns for a complete graph.
+
+**New dependencies:** None (custom implementation).
+
+---
+
+## Phase 4: AI Semantic Enrichment
+
+**Goal:** Use AI to explain the *why* and *how* of each file — skip with `--no-ai`.
+
+**Input:** File content + `dependents[]` list + `symbols[]`.
+**Output:** `semantic: SemanticInfo` per file + `.semantic.md` files on disk.
+
+**How it works:**
+
+1. **GEMINI_API_KEY validation:** At `SemanticEnricher` construction time (before any API calls), check `process.env.GEMINI_API_KEY`. If absent and `config.graph.ai_enrichment` is true, throw `NomosError('graph_ai_key_missing', 'GEMINI_API_KEY environment variable is not set.')`.
+
+2. **Staleness filter:** Enrich a file only when:
+   - `FileNode.semantic === null`, OR
+   - `FileNode.hash !== FileNode.semantic.source_hash` (file changed since last enrichment)
+
+3. **Prompt per file** (content truncated at last complete line boundary before `config.graph.max_file_chars` characters):
+   ```
+   File: {relative_path}
+   Language: {language}
+   Exports: {symbol names and signatures}
+   Used by: {dependent file list}
+   ---
+   {file content}
+   ---
+   Respond in JSON matching this schema exactly:
+   { "overview": string, "purpose": string, "key_logic": string[], "usage_context": string[] }
+   ```
+
+4. **Gemini structured output:** Pass `responseSchema` to `generationConfig`:
+   ```typescript
+   const responseSchema = {
+     type: 'object',
+     properties: {
+       overview:      { type: 'string' },
+       purpose:       { type: 'string' },
+       key_logic:     { type: 'array', items: { type: 'string' } },
+       usage_context: { type: 'array', items: { type: 'string' } },
+     },
+     required: ['overview', 'purpose', 'key_logic', 'usage_context'],
+   };
+   ```
+
+5. **Rate limiting:** Gemini 1.5 Flash free tier allows 15 RPM. Use `p-limit` with concurrency = `config.graph.ai_concurrency` (default 5) and a minimum 4-second gap between requests (4s × 15 = 60s window).
+
+6. **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 `[nomos:graph:error] AI enrichment failed for {file} after 3 retries — skipping`.
+
+7. **Zod validation:** If the response parses but fails Zod validation, log the raw response (truncated to 200 chars) and set `semantic: null`. Do not throw.
+
+8. **Populate SemanticInfo:**
+   ```typescript
+   {
+     overview, purpose, key_logic, usage_context,
+     source_hash: fileNode.hash,   // snapshot the current hash
+     enriched_at: new Date().toISOString(),
+     model: config.graph.ai_model,
+   }
+   ```
+
+9. **Write `.semantic.md` Semantic Contract** next to the source file:
+   - `src/core/state.ts` → write `src/core/state.semantic.md`
+   - If the file already exists AND `source_hash` matches the current hash, skip writing (no change)
+   - Template:
+     ```markdown
+     # state.ts — Semantic Contract
+     > Auto-generated by `arc map` — do not edit manually.
+
+     ## Overview
+     {overview}
+
+     ## Purpose
+     {purpose}
+
+     ## Key Logic
+     {key_logic as numbered list}
+
+     ## Usage Context
+     Used by: {dependent files}
+     {usage_context as bullet list}
+
+     ---
+     *Enriched at: {enriched_at} | Model: {model}*
+     ```
+
+10. **Graceful degradation:** A failed file never blocks the pipeline. The map is written with `semantic: null` for failed files.
+
+**New dependencies:** `@google/generative-ai`, `p-limit`
+
+**esbuild note:** Add `--external:@google/generative-ai` to the build script (ESM/CJS compatibility).
+
+---
+
+## Phase 5: Output & Consumption
+
+**Goal:** Write `project_map.json` atomically and inject Architectural Constraints into `arc plan`.
+
+**Output artifacts:**
+- `{config.graph.output_dir}/project_map.json` — full map, JSON, source of truth.
+- `*.semantic.md` files next to each source file (written in Phase 4).
+
+**Atomic write for `project_map.json`:**
+Follow the same `tmp → fsync → rename` pattern used by `StateManager.write()` in `src/core/state.ts`:
+```typescript
+const outDir  = path.join(projectRoot, config.graph.output_dir);
+await fs.mkdir(outDir, { recursive: true });
+const mapPath = path.join(outDir, 'project_map.json');
+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);
+```
+If the write fails, throw `NomosError('graph_write_failed', ...)`.
+
+**Architectural Constraint injection into `arc plan`:**
+
+The injection happens in THREE layers:
+
+**Layer 5.4a — Extend `PromptOptions`** (`src/types/index.ts`):
+```typescript
+export interface PromptOptions {
+  // ... existing fields ...
+  architecturalConstraints: string | null;  // null when no project_map.json exists
+}
+```
+
+**Layer 5.4b — Implement `readArchitecturalConstraints`** (new utility in `src/core/graph/constraints.ts`):
+```typescript
+export async function readArchitecturalConstraints(
+  projectRoot: string,
+  outputDir: string,
+  contextFiles: string[],
+): Promise<string | null>
+```
+- Reads `project_map.json` from `path.join(projectRoot, outputDir, 'project_map.json')`
+- If file does not exist, returns `null` (no constraints injected — not an error)
+- For each `contextFile`, look it up in `ProjectMap.files`
+  - If absent from map: log `[nomos:graph:warn] {file} not in project map — run arc map to update` and skip it
+- For each found `FileNode`, collect `dependents[]` that have non-null `semantic`, and identify the specific `symbols[]` they consume
+- Build the constraint string (see format below)
+- Returns `null` if no constraints were found
+
+**Layer 5.4c — Wire into `Orchestrator.plan()`** (`src/core/orchestrator.ts`):
+- Before calling `assemblePrompt(...)`, call `readArchitecturalConstraints(projectRoot, config.graph.output_dir, contextFiles)`
+- Pass the result into `PromptOptions.architecturalConstraints`
+
+**Constraint section format in `assemblePrompt`** (`src/core/prompt.ts`):
+```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
+  );
+}
+```
+
+**Constraint string example:**
+```
+- src/core/state.ts → symbol: readState(taskId: string): TaskState
+  Consumed by: orchestrator.ts, status.ts
+  Contract: "Return type must remain TaskState — orchestrator destructures .version and .status directly"
+
+- src/adapters/git.ts → symbol: commitToShadowBranch(files: string[]): Promise<void>
+  Consumed by: apply.ts, worktree-coordinator.ts
+  Contract: "Parameter must remain string[] — callers build the list explicitly"
+```
+
+---
+
+## Phase 6: Visualization — `arc show map`
+
+**Goal:** Generate a standalone interactive HTML graph visualizing the dependency hierarchy.
+
+**Input:** `project_map.json`
+**Output:** `{config.graph.output_dir}/index.html` — opens in browser, zero server needed.
+
+**Missing map behavior:** If `project_map.json` does not exist, exit with code 1:
+```
+[nomos:error] No project map found. Run: arc map first.
+```
+
+**How it works:**
+1. **Read `project_map.json`**, run `migrateProjectMap()` on load. Transform into Cytoscape.js graph format:
+   - Each `FileNode` → **node** (label = filename, data = full FileNode)
+   - Each dependency link → **directed edge** (source → target)
+2. **Layout:** Cytoscape **Breadth-First (BFS) layout** — roots at top (core modules), leaves at bottom.
+3. **Depth-based coloring:**
+   - Map each file's `depth` to a color gradient:
+     - **Depth 0 (leaves/entry points):** `#a8d8ea` — cool blue (low risk)
+     - **Mid depth:** `#f9c784` — warm amber (moderate risk)
+     - **Max depth (core):** `#c0392b` — deep red (high risk — modify carefully)
+   - Visual danger signal: darker = more files depend on this.
+4. **Visual Ripple Analysis:** On node click, propagate a highlight across the graph:
+   - **Red (`#e74c3c`):** direct dependents (`dependents[]`, depth +1) — files that immediately break
+   - **Yellow (`#f39c12`):** transitive dependents (dependents of dependents) — indirect blast radius
+   - All other nodes dim to `#bdc3c7` (grey), making the blast radius instantly visible
+   - Click empty canvas to reset all highlights to default depth coloring
+5. **Interactive Context Cards:** Clicking a node expands a fixed side panel (right, 320px) showing:
+   - Filename + language badge
+   - `semantic.overview` and `semantic.purpose` (or "Run arc map --ai to enrich" if `semantic === null`)
+   - `dependents[]` list as clickable items that re-center the graph on that node
+   - `symbols[]` list with kind badges and signatures
+6. **Symbol Search & Path Tracing:** A search input in the top bar:
+   - Accepts a symbol name (e.g. `readState`) or file path fragment (e.g. `state`)
+   - Matches against `FileNode.symbols[].name` and `FileNode.file`
+   - Highlights all matched nodes in **green** and dims the rest
+   - Traces the full dependency path: for each match, also highlights the chain of importers
+   - Results update live (client-side filter against embedded JSON — no server needed)
+   - Press Escape or clear the input to reset
+7. **Generate standalone HTML:**
+   - Cytoscape.js pinned CDN: `https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.28.1/cytoscape.min.js`
+   - Embed `project_map.json` data inline as `const PROJECT_MAP = { ... };`
+   - One self-contained `index.html` — no build step, no server
+
+**Browser open:** Use the `open` npm package (not `child_process.exec` — shell injection risk). Call `open(htmlPath)` only when `--no-open` flag is absent.
+
+**esbuild note:** Add `--external:open` to the build script.
+
+**`arc show map` commander registration:**
+`arc show map` is a nested subcommand. Register a parent `show` command group first:
+```typescript
+// In src/commands/show.ts
+export function registerShowCommand(program: Command): void {
+  const show = program.command('show').description('Display visual outputs');
+  show
+    .command('map')
+    .description('Open the interactive dependency graph in your browser')
+    .option('--no-open', 'Generate index.html without opening browser')
+    .action(async (opts) => { /* ... */ });
+}
+```
+
+**New dependencies:** `open` (runtime), `@types/cytoscape` (devDependency for template type safety)
+
+---
+
+## Atomic Implementation Plan
+
+Each task is a single, testable unit of work. Tasks within a phase can be parallelized.
+
+### Phase 0: Prerequisites (do before any graph code)
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 0.1 | Add `fast-glob`, `gitignore-parser`, `p-limit`, `open` to `package.json` | `package.json` | — |
+| 0.2 | Add `tree-sitter`, `tree-sitter-typescript`, `@google/generative-ai` to `package.json` and update esbuild script with `--external:tree-sitter --external:tree-sitter-typescript --external:@google/generative-ai --external:open` | `package.json` | 0.1 |
+| 0.3 | Add new `NomosErrorCode` values (`graph_map_not_found`, `graph_parse_error`, `graph_ai_key_missing`, `graph_write_failed`) to `src/core/errors.ts` | `src/core/errors.ts` | — |
+| 0.4 | Update `.gitignore` — add `*.semantic.md` and `tasks-management/graph/` entries, document the VCS policy | `.gitignore` | — |
+
+### Phase 1: Foundation (File Discovery)
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 1.1 | Define all Semantic Graph types in `src/types/index.ts` (`FileNode`, `SymbolEntry`, `ImportEntry`, `SemanticInfo`, `ProjectMap`) | `src/types/index.ts` | 0.3 |
+| 1.2 | Add `graph` section to `NomosConfig` interface and `GraphConfigSchema` Zod schema with all defaults | `src/types/index.ts`, `src/core/config.ts` | 1.1 |
+| 1.3 | Implement `ProjectMapSchema`, `migrateProjectMap()`, and `readProjectMap()` (atomic read + migration) | `src/core/graph/map-schema.ts` | 1.1 |
+| 1.4 | Implement `FileScanner` — gitignore-aware glob + hash + language detection + incremental skip logic | `src/core/graph/scanner.ts` | 0.1, 1.1 |
+| 1.5 | Test `FileScanner` — finds files, computes hashes, detects languages, excludes node_modules, handles unreadable files, skips unchanged hashes, respects --force | `src/core/graph/__tests__/scanner.test.ts` | 1.4 |
+
+### Phase 2: Parsing (Symbol Extraction)
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 2.1 | Implement `ASTParser` — grammar selection (ts vs tsx), error-node threshold check, symbol extraction with `end_line` and method names | `src/core/graph/parser.ts` | 0.2, 1.1 |
+| 2.2 | Implement import extraction in `ASTParser` — populate `ImportEntry.source` and `symbols[]`, leave `resolved: null` | `src/core/graph/parser.ts` | 2.1 |
+| 2.3 | Test `ASTParser` — symbols + imports from sample TS files, tsx grammar selection, error-node fallback, class method extraction | `src/core/graph/__tests__/parser.test.ts` | 2.1, 2.2 |
+
+### Phase 3: Graph (Dependencies & Topology)
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 3.1 | Implement `ImportResolver` — relative path resolution (extensions + index), tsconfig alias resolution, external detection, path traversal guard | `src/core/graph/resolver.ts` | 1.1 |
+| 3.2 | Implement `GraphBuilder` — adjacency list, Kahn's BFS depth, cycle detection with warning, `stats.core_modules` | `src/core/graph/builder.ts` | 1.1, 3.1 |
+| 3.3 | Test `ImportResolver` — relative paths, index resolution, tsconfig aliases with wildcards, externals, path traversal, unresolvable paths | `src/core/graph/__tests__/resolver.test.ts` | 3.1 |
+| 3.4 | Test `GraphBuilder` — forward/reverse edges, depth calc, 2-node cycle, 3-node cycle, `core_modules` extraction | `src/core/graph/__tests__/builder.test.ts` | 3.2 |
+
+### Phase 4: AI Enrichment + Semantic Contracts
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 4.1 | Implement `SemanticEnricher` — GEMINI_API_KEY validation, staleness check via `source_hash`, prompt builder with line-boundary truncation, Gemini structured output call, Zod validation, retry policy (3x backoff on 429/503), p-limit rate limiter | `src/core/graph/enricher.ts` | 0.1, 0.2, 1.1, 1.2, 2.1, 3.2 |
+| 4.2 | Implement `ContractWriter` — renders `SemanticInfo` into `.semantic.md` using source_hash for overwrite skip | `src/core/graph/contract-writer.ts` | 1.1 |
+| 4.3 | Test `SemanticEnricher` — mock `@google/generative-ai` with `vi.mock()`, validate staleness check, Zod failure fallback, retry on 429, key missing error | `src/core/graph/__tests__/enricher.test.ts` | 4.1 |
+| 4.4 | Test `ContractWriter` — generates correct Markdown structure, skips overwrite when source_hash unchanged, overwrites when hash changed | `src/core/graph/__tests__/contract-writer.test.ts` | 4.2 |
+
+### Phase 5: Command & Integration
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 5.1 | Implement `MapPipeline` — constructor `(config: NomosConfig, projectRoot: string, logger: Logger)`, chains scanner → parser → resolver → builder → enricher → contract-writer, creates `tasks-management/graph/` dir, atomic write of `project_map.json` | `src/core/graph/pipeline.ts` | 1.4, 2.1, 3.1, 3.2, 4.1, 4.2 |
+| 5.2 | Implement `arc map` command — wires `MapPipeline` via `createOrchestrator()` factory, handles `--no-ai` (sets `config.graph.ai_enrichment = false`), `--force`, and glob args; exits 0 on success, 1 on fatal error, 2 on partial AI failure | `src/commands/map.ts` | 5.1 |
+| 5.3 | Register `arc map` in CLI entry point | `src/cli.ts` | 5.2 |
+| 5.4a | Extend `PromptOptions` with `architecturalConstraints: string \| null` | `src/types/index.ts` | 1.1 |
+| 5.4b | Implement `readArchitecturalConstraints(projectRoot, outputDir, contextFiles): Promise<string \| null>` — reads map, skips missing files with warning, builds constraint string with symbol signatures | `src/core/graph/constraints.ts` | 1.3, 5.4a |
+| 5.4c | Wire `readArchitecturalConstraints` into `Orchestrator.plan()` before `assemblePrompt`; add `[ARCHITECTURAL CONSTRAINTS]` section to `assemblePrompt` in `prompt.ts` | `src/core/orchestrator.ts`, `src/core/prompt.ts` | 5.4a, 5.4b |
+| 5.5 | Test `MapPipeline` end-to-end — scan + parse + resolve + build on `test/fixtures/sample-project/` fixture; incremental run skips unchanged files; `--force` re-parses all | `src/core/graph/__tests__/pipeline.test.ts` | 5.1 |
+| 5.6 | Test Architectural Constraint injection — write minimal `project_map.json` to tmpdir, assert `[ARCHITECTURAL CONSTRAINTS]` section appears in assembled prompt with correct symbol signatures; assert missing-from-map files log a warning | `src/core/__tests__/prompt.test.ts` | 5.4c |
+
+### Phase 6: Visualization (`arc show map`)
+
+| # | Task | Deliverables | Depends On |
+|---|------|-------------|------------|
+| 6.1 | Implement `MapRenderer` — transforms `ProjectMap` into Cytoscape.js node/edge JSON, computes depth-to-hex-color mapping using the pinned gradient | `src/core/graph/renderer.ts` | 1.1 |
+| 6.2a | Create HTML template — static shell, CDN Cytoscape.js (pinned 3.28.1), BFS layout, depth coloring via inline `<style>` | `src/core/graph/html-template.ts` | 6.1 |
+| 6.2b | Add click-to-expand context card panel to HTML template — side panel with overview, purpose, dependents (clickable), symbols list | `src/core/graph/html-template.ts` | 6.2a |
+| 6.2c | Add ripple analysis to HTML template — on node click: highlight direct dependents red, transitive yellow, dim rest; click canvas to reset | `src/core/graph/html-template.ts` | 6.2b |
+| 6.2d | Add symbol search bar to HTML template — live filter matching `FileNode.symbols[].name` and `FileNode.file`, highlight matches in green + trace dependency path | `src/core/graph/html-template.ts` | 6.2c |
+| 6.3 | Implement `arc show map` command — reads map via `readProjectMap()`, calls `MapRenderer`, writes `index.html` to `output_dir`, opens with `open` package (unless `--no-open`) | `src/commands/show.ts` | 6.1, 6.2d |
+| 6.4 | Register `arc show map` under a `show` parent command group in CLI entry point | `src/cli.ts` | 6.3 |
+| 6.5 | Test `MapRenderer` — correct node/edge counts, color gradient mapping at depth 0 / mid / max, context card data fields, empty-map edge case | `src/core/graph/__tests__/renderer.test.ts` | 6.1 |
+| 6.6 | Test `arc show map` command — map missing → exit 1 with correct message; map present → `index.html` written to correct path; `--no-open` suppresses browser launch | `src/core/graph/__tests__/show.test.ts` | 6.3 |
+
+---
+
+## Test Fixture — `test/fixtures/sample-project/`
+
+All graph tests share a minimal fixture project with known relationships. Create these files:
+
+```
+test/fixtures/sample-project/
+  tsconfig.json              # { "compilerOptions": { "paths": { "@/utils": ["src/utils/index.ts"] } } }
+  src/
+    types.ts                 # exports: interface User, type UserId
+    utils/
+      index.ts               # exports: function hash(s: string): string — imports nothing
+      format.ts              # exports: function formatUser(u: User): string — imports ../types, @/utils
+    service.ts               # exports: class UserService — imports ./types, ./utils/index
+    main.ts                  # imports ./service — no exports (entry point)
+    circular-a.ts            # imports ./circular-b
+    circular-b.ts            # imports ./circular-a
+```
+
+Expected graph properties:
+- `src/types.ts` and `src/utils/index.ts` are the highest-depth nodes (most imported)
+- `src/main.ts` is depth 0 (nobody imports it)
+- `circular-a.ts` and `circular-b.ts` form a 2-node cycle
+
+---
+
+## Dependency Summary
+
+| Package | Purpose | Phase | esbuild |
+|---------|---------|-------|---------|
+| `fast-glob` | File discovery | 1 | bundled |
+| `gitignore-parser` | Parse `.gitignore` for fast-glob ignore list | 1 | bundled |
+| `tree-sitter` | AST parsing engine | 2 | `--external` |
+| `tree-sitter-typescript` | TS/TSX grammar | 2 | `--external` |
+| `@google/generative-ai` | Gemini 1.5 Flash SDK | 4 | `--external` |
+| `p-limit` | Concurrency limiter for AI requests | 4 | bundled |
+| `open` | Cross-platform browser open | 6 | `--external` |
+| `zod` (existing) | Validate AI responses + ProjectMapSchema | 1, 4 | bundled |
+| `node:crypto` (built-in) | SHA-256 hashing | 1 | built-in |
+| `cytoscape` (CDN in HTML) | Interactive graph visualization | 6 | CDN only |
+
+---
+
+## File Structure
+
+```
+src/core/graph/
+  map-schema.ts       # ProjectMapSchema, migrateProjectMap(), readProjectMap()
+  scanner.ts          # Phase 1 — gitignore-aware file discovery + hashing
+  parser.ts           # Phase 2 — tree-sitter AST + symbol + import extraction
+  resolver.ts         # Phase 3 — import path resolution (relative, alias, external)
+  builder.ts          # Phase 3 — dependency graph + Kahn's BFS topological sort
+  enricher.ts         # Phase 4 — Gemini AI semantic enrichment with retry + rate limit
+  contract-writer.ts  # Phase 4 — writes .semantic.md files next to source
+  constraints.ts      # Phase 5 — reads project_map.json, builds constraint strings
+  pipeline.ts         # Phase 5 — chains all phases (was: orchestrator.ts — renamed to avoid clash)
+  renderer.ts         # Phase 6 — transforms ProjectMap to Cytoscape.js format
+  html-template.ts    # Phase 6 — standalone HTML with Cytoscape.js + all interactive features
+  __tests__/
+    scanner.test.ts
+    parser.test.ts
+    resolver.test.ts
+    builder.test.ts
+    enricher.test.ts
+    contract-writer.test.ts
+    pipeline.test.ts
+    renderer.test.ts
+    show.test.ts
+
+src/commands/map.ts   # CLI command: arc map
+src/commands/show.ts  # CLI command group: arc show [map]
+```
+
+---
+
+## CLI Interface
+
+```bash
+# Full map with AI enrichment (requires GEMINI_API_KEY env var)
+arc map
+
+# Structural only — no AI tokens spent (sets config.graph.ai_enrichment = false)
+arc map --no-ai
+
+# Force re-analysis of all files (ignore hashes)
+arc map --force
+
+# Map only specific directories/patterns
+arc map "src/core/**" "src/commands/**"
+
+# Open the interactive visual graph in the browser
+arc show map
+
+# Generate HTML only, don't open browser
+arc show map --no-open
+
+# Output locations:
+# -> {config.graph.output_dir}/project_map.json   (default: tasks-management/graph/)
+# -> {config.graph.output_dir}/index.html
+# -> src/**/*.semantic.md  (one per source file, written during AI enrichment)
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success — map written, all operations completed |
+| `1` | Fatal error — config not found, I/O failure, key missing |
+| `2` | Partial failure — map written but some AI enrichment failed |
+| `130` | Interrupted — SIGINT (follows existing CLI convention) |
+
+### stdout vs stderr
+
+- **Progress output** (files scanned, AI per-file status) → **stderr** (so stdout is pipeable)
+- **Final summary line** (e.g. `Mapped 32 files, enriched 28, 4 skipped`) → **stdout**
+- Zero files matched by glob patterns → `[nomos:graph:warn] No files matched — is the pattern correct?` on stderr, exit 0
+
+---
+
+## Execution Rules Compliance Notes
+
+| Rule | Compliance |
+|------|-----------|
+| Rule 3 — JSON source of truth | `.semantic.md` files are write-only rendered views. All programmatic reads use `project_map.json`. No code path reads `.semantic.md`. |
+| Rule 6 — ESM | All imports use `.js` extensions. `html-template.ts` (not `.html.ts`) avoids `.html.js` import weirdness. |
+| Rule 10 — Shell injection | `arc show map` uses the `open` package or `spawn(cmd, [path], { shell: false })`. Never `exec(\`open ${path}\`)`.|
+| Rule 11 — Schema versioning | `ProjectMap.schema_version` starts at 1. `migrateProjectMap()` exists in `map-schema.ts` with empty but present `migrations` map. |
+| Rule 14 — No wildcard git adds | `arc map` and `arc show map` write only to `tasks-management/graph/` and `*.semantic.md`. These paths are gitignored (task 0.4). No git operations in the map pipeline. |
+
+---
+
+## Success Criteria
+
+- [ ] `arc map --no-ai` completes in under 5 seconds on this project (~30 files)
+- [ ] `project_map.json` accurately reflects all imports, exports, and depth values
+- [ ] Incremental run (no file changes) skips all parsing and completes in < 1 second
+- [ ] `project_map.json` is written atomically (tmp → fsync → rename)
+- [ ] `--force` causes all files to be re-parsed regardless of hash
+- [ ] AI enrichment writes `.semantic.md` files next to each source file
+- [ ] `.semantic.md` files are human-readable and contain all four pillars (Overview, Purpose, Key Logic, Usage Context)
+- [ ] `arc map` exits 2 (not 1) when some AI calls fail but the map is still written
+- [ ] `arc plan` prompt includes `[ARCHITECTURAL CONSTRAINTS]` section with symbol signatures when `project_map.json` exists
+- [ ] Missing context files log a warning and are gracefully skipped (not a crash)
+- [ ] AI enrichment gracefully handles API failures without blocking the map (sets `semantic: null`)
+- [ ] `arc show map` generates a standalone `index.html` with Cytoscape.js 3.28.1 BFS layout
+- [ ] Graph nodes are colored by topological depth (red = core/high-risk, blue = leaf/low-risk)
+- [ ] Clicking a node shows ripple analysis (direct dependents red, transitive yellow, rest dimmed)
+- [ ] Symbol search highlights matching nodes and traces their dependency path
+- [ ] Clicking a node shows its semantic overview, dependents list, and exported symbols
+- [ ] `arc show map` exits 1 with a clear message when `project_map.json` is missing
+- [ ] All 9 test files pass (`scanner`, `parser`, `resolver`, `builder`, `enricher`, `contract-writer`, `pipeline`, `renderer`, `show`)