@nomos-arc/arc 0.1.0

package/docs/infrastructure/map.md

@@ -0,0 +1,867 @@
+# `arc map` — Semantic Dependency Mapping
+
+> **Command**: `arc map [patterns...] [--no-ai] [--force]`
+> **Purpose**: Scan project files, parse their AST, resolve imports, build a dependency graph, and optionally enrich each file with AI-generated semantic descriptions.
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Command Interface](#command-interface)
+- [Pipeline Architecture](#pipeline-architecture)
+- [Stage-by-Stage Breakdown](#stage-by-stage-breakdown)
+  - [Stage A — Read Existing Map](#stage-a--read-existing-map)
+  - [Stage B — File Scanning](#stage-b--file-scanning)
+  - [Stage C — Empty Check](#stage-c--empty-check)
+  - [Stage D — AST Parser Initialization](#stage-d--ast-parser-initialization)
+  - [Stage E — Parse Files](#stage-e--parse-files)
+  - [Stage F — Merge Parsed + Carried](#stage-f--merge-parsed--carried)
+  - [Stage G — Import Resolution](#stage-g--import-resolution)
+  - [Stage H — Graph Building](#stage-h--graph-building)
+  - [Stage I — Intermediate Map Write](#stage-i--intermediate-map-write)
+  - [Stage J — AI Semantic Enrichment](#stage-j--ai-semantic-enrichment)
+  - [Stage K — Contract Writing](#stage-k--contract-writing)
+  - [Stage L — Final Map Write](#stage-l--final-map-write)
+- [Data Structures](#data-structures)
+- [Graph Algorithms](#graph-algorithms)
+- [AI Enrichment Deep Dive](#ai-enrichment-deep-dive)
+- [Incremental Processing](#incremental-processing)
+- [Concurrency & Safety](#concurrency--safety)
+- [Configuration Reference](#configuration-reference)
+- [Output Files](#output-files)
+- [Exit Codes](#exit-codes)
+- [File Map (Source Code)](#file-map-source-code)
+- [Design Decisions & Fixes](#design-decisions--fixes)
+
+---
+
+## Overview
+
+The `arc map` command is the codebase intelligence engine of nomos-arc.ai. It produces a **`project_map.json`** file that serves as a structured, machine-readable representation of the entire project: every file, symbol, import, dependency edge, and (optionally) AI-generated semantic summary.
+
+Other commands (`arc plan`, `arc review`) consume this map to understand the codebase without re-scanning it.
+
+```
+                    +-----------+
+                    |  arc map  |
+                    +-----+-----+
+                          |
+          +---------------+---------------+
+          |               |               |
+    +-----------+   +-----------+   +-----------+
+    |   Scan    |   |   Parse   |   |   Enrich  |
+    | (fs+glob) |   | (AST/WASM)|   | (Gemini)  |
+    +-----------+   +-----------+   +-----------+
+          |               |               |
+          +---------------+---------------+
+                          |
+                  +-------+-------+
+                  | project_map   |
+                  |   .json       |
+                  +---------------+
+```
+
+---
+
+## Command Interface
+
+```bash
+arc map [patterns...] [--no-ai] [--force]
+```
+
+| Argument / Flag   | Description                                                        |
+|-------------------|--------------------------------------------------------------------|
+| `[patterns...]`   | Glob patterns to scope the scan (default: `**/*`)                  |
+| `--no-ai`         | Skip AI enrichment; produce structural map only                    |
+| `--force`         | Re-parse all files even if their hash hasn't changed               |
+
+**Examples**:
+
+```bash
+arc map                          # Full scan + AI enrichment
+arc map "src/**/*.ts"            # Only map TypeScript files in src/
+arc map --no-ai                  # Structural map, no Gemini calls
+arc map --force                  # Re-parse everything from scratch
+arc map "src/**" --no-ai --force # Combined flags
+```
+
+---
+
+## Pipeline Architecture
+
+The map command delegates all work to `MapPipeline`, which executes a strict sequence of stages. Each stage has a single responsibility and passes data forward to the next.
+
+```mermaid
+flowchart TD
+    CMD["arc map [patterns] [flags]"]
+    CMD --> CFG["Load .nomos-config.json"]
+    CFG --> LOG["Create Logger"]
+    LOG --> AUTH["Initialize AuthManager"]
+    AUTH --> PIPE["MapPipeline.run()"]
+
+    PIPE --> A["A: Read existing map"]
+    A --> B["B: Scan filesystem"]
+    B --> C{"C: Any files found?"}
+    C -- No --> EMPTY["Return empty map"]
+    C -- Yes --> D["D: Init ASTParser (WASM)"]
+    D --> E["E: Parse new/changed files"]
+    E --> F["F: Merge parsed + carried"]
+    F --> G["G: Resolve imports (8 workers)"]
+    G --> H["H: Build dependency graph"]
+    H --> I["I: Write intermediate map"]
+    I --> AI{"AI enrichment enabled?"}
+    AI -- No --> RET["Return map"]
+    AI -- Yes --> J["J: Enrich via Gemini"]
+    J --> K["K: Write .semantic.md contracts"]
+    K --> L["L: Write final map"]
+    L --> RET
+
+    style CMD fill:#2d3748,stroke:#4a5568,color:#e2e8f0
+    style PIPE fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style A fill:#2f855a,stroke:#276749,color:#fff
+    style B fill:#2f855a,stroke:#276749,color:#fff
+    style C fill:#d69e2e,stroke:#b7791f,color:#000
+    style D fill:#2f855a,stroke:#276749,color:#fff
+    style E fill:#2f855a,stroke:#276749,color:#fff
+    style F fill:#2f855a,stroke:#276749,color:#fff
+    style G fill:#2f855a,stroke:#276749,color:#fff
+    style H fill:#805ad5,stroke:#6b46c1,color:#fff
+    style I fill:#dd6b20,stroke:#c05621,color:#fff
+    style J fill:#e53e3e,stroke:#c53030,color:#fff
+    style K fill:#dd6b20,stroke:#c05621,color:#fff
+    style L fill:#dd6b20,stroke:#c05621,color:#fff
+    style EMPTY fill:#718096,stroke:#4a5568,color:#fff
+    style RET fill:#718096,stroke:#4a5568,color:#fff
+    style AI fill:#d69e2e,stroke:#b7791f,color:#000
+```
+
+---
+
+## Stage-by-Stage Breakdown
+
+### Stage A — Read Existing Map
+
+**File**: `src/core/graph/map-schema.ts`
+
+Reads `tasks-management/graph/project_map.json` from disk. Returns `null` if the file doesn't exist (first run). Validates against a Zod schema with a forward-compatibility ceiling check — if the file's `schema_version` is newer than what this CLI version supports, it throws an error prompting the user to upgrade.
+
+```mermaid
+flowchart LR
+    READ["Read project_map.json"] --> EXISTS{"File exists?"}
+    EXISTS -- Yes --> VALIDATE["Zod schema validation"]
+    EXISTS -- No --> NULL["Return null"]
+    VALIDATE --> VERSION{"schema_version <= current?"}
+    VERSION -- Yes --> RETURN["Return ProjectMap"]
+    VERSION -- No --> ERROR["Error: upgrade CLI"]
+
+    style READ fill:#2f855a,stroke:#276749,color:#fff
+    style ERROR fill:#e53e3e,stroke:#c53030,color:#fff
+```
+
+### Stage B — File Scanning
+
+**File**: `src/core/graph/scanner.ts` | **Class**: `FileScanner`
+
+Uses `fast-glob` to discover files matching the given patterns. Applies a multi-layer filter:
+
+```mermaid
+flowchart TD
+    GLOB["fast-glob(patterns)"] --> IGNORE["Apply ignore patterns"]
+    IGNORE --> LANG{"Supported language?"}
+    LANG -- No --> SKIP1["Skip file"]
+    LANG -- "TS/TSX/JS/JSX/PY/GO/RS" --> SIZE{"Size <= 500KB?"}
+    SIZE -- No --> SKIP2["Skip file"]
+    SIZE -- Yes --> HASH["Compute SHA256 hash"]
+    HASH --> CHANGED{"Hash changed from existing map?"}
+    CHANGED -- "Yes (or --force)" --> NEW["Add to 'files' (new)"]
+    CHANGED -- No --> CARRY["Add to 'carried' (reuse)"]
+
+    style GLOB fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style NEW fill:#2f855a,stroke:#276749,color:#fff
+    style CARRY fill:#805ad5,stroke:#6b46c1,color:#fff
+    style SKIP1 fill:#718096,stroke:#4a5568,color:#fff
+    style SKIP2 fill:#718096,stroke:#4a5568,color:#fff
+```
+
+**Ignore sources**:
+- Config `graph.exclude_patterns` (defaults: `node_modules`, `dist`, `*.test.*`, `*.spec.*`, `*.semantic.md`)
+- `.gitignore` in project root
+
+**Supported languages**: TypeScript, TSX, JavaScript, JSX, Python, Go, Rust
+
+**Output**: `ScanResult { files: Map, carried: Map }`
+
+### Stage C — Empty Check
+
+If both `files` and `carried` are empty (no scannable files found), immediately returns an empty `ProjectMap` with zero stats. No further stages execute.
+
+### Stage D — AST Parser Initialization
+
+**File**: `src/core/graph/parser.ts` | **Class**: `ASTParser`
+
+Initializes `web-tree-sitter` (WASM-based parser). Grammar `.wasm` files are loaded from:
+
+1. `tree-sitter-wasms` npm package (primary)
+2. Local `./grammars/` directory (fallback)
+
+Grammar path resolution is handled by `src/core/graph/grammar-paths.ts`.
+
+> **Why WASM?** [BLK-1] Native `.node` tree-sitter bindings cause portability issues across platforms and Node versions. WASM provides uniform behavior everywhere.
+
+### Stage E — Parse Files
+
+For each newly scanned file, the AST parser extracts:
+
+```mermaid
+flowchart LR
+    FILE["Source file"] --> TREE["tree-sitter parse"]
+    TREE --> SYMBOLS["Extract symbols"]
+    TREE --> IMPORTS["Extract imports"]
+
+    SYMBOLS --> FN["Functions"]
+    SYMBOLS --> CLS["Classes + Methods"]
+    SYMBOLS --> IF["Interfaces"]
+    SYMBOLS --> TP["Types"]
+    SYMBOLS --> EN["Enums"]
+    SYMBOLS --> VAR["Variables"]
+
+    IMPORTS --> ES6["ES6 imports"]
+    IMPORTS --> REQ["require() calls"]
+
+    style FILE fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style TREE fill:#805ad5,stroke:#6b46c1,color:#fff
+```
+
+**Error threshold**: If >20% of the parsed tree consists of ERROR nodes (malformed syntax), the parser returns an empty result for that file rather than producing garbage data.
+
+**Semantic carry-forward**: If the file's hash matches the existing map entry, the previous `semantic` data is preserved on the new node.
+
+### Stage F — Merge Parsed + Carried
+
+Merges newly parsed `FileNode` entries with carried (unchanged) entries into a single `allFiles` map. Parsed entries overwrite carried ones if both exist for the same path.
+
+### Stage G — Import Resolution
+
+**File**: `src/core/graph/resolver.ts` | **Class**: `ImportResolver`
+
+Runs with **8 concurrent workers** (via `p-limit`) to resolve every import in every file.
+
+```mermaid
+flowchart TD
+    IMP["Import source string"] --> REL{"Starts with . or /?"}
+    REL -- No --> ALIAS{"Matches tsconfig path alias?"}
+    ALIAS -- No --> EXT["Mark as external"]
+    ALIAS -- Yes --> SUBST["Substitute alias path"]
+    SUBST --> PROBE
+
+    REL -- Yes --> PROBE["Probe extensions"]
+    PROBE --> TS[".ts"]
+    PROBE --> TSX[".tsx"]
+    PROBE --> JS[".js"]
+    PROBE --> IDX["index.ts/tsx/js"]
+
+    TS --> KNOWN{"In knownFiles Set?"}
+    TSX --> KNOWN
+    JS --> KNOWN
+    IDX --> KNOWN
+
+    KNOWN -- Yes --> RESOLVED["resolved = relative path"]
+    KNOWN -- No --> UNRESOLVED["resolved = null"]
+
+    style IMP fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style EXT fill:#dd6b20,stroke:#c05621,color:#fff
+    style RESOLVED fill:#2f855a,stroke:#276749,color:#fff
+    style UNRESOLVED fill:#e53e3e,stroke:#c53030,color:#fff
+```
+
+**Critical contract [WATCH-4]**: The resolver makes **zero filesystem calls**. All existence checks use `.has()` on a `knownFiles: Set<string>` populated from both scanned and carried files. This makes resolution fast and deterministic.
+
+**Tsconfig support**: Reads `tsconfig.json` `compilerOptions.paths` for wildcard aliases (e.g., `@/* -> src/*`).
+
+**Path traversal guard**: Any resolved path that escapes `projectRoot` is marked as external.
+
+### Stage H — Graph Building
+
+**File**: `src/core/graph/builder.ts` | **Class**: `GraphBuilder`
+
+Builds the dependency graph and computes topological depth for every file.
+
+```mermaid
+flowchart TD
+    FILES["All FileNodes"] --> RESET["Reset graph fields"]
+    RESET --> ADJ["Build adjacency lists"]
+    ADJ --> DEP_OUT["dependencies (edges OUT)"]
+    ADJ --> DEP_IN["dependents (edges IN)"]
+
+    DEP_IN --> INDEG["Calculate in-degree"]
+    INDEG --> KAHN["Kahn's BFS Topological Sort"]
+
+    KAHN --> QUEUE["Queue: nodes with in-degree 0"]
+    QUEUE --> PROCESS["Process queue"]
+    PROCESS --> DEPTH["Assign depth = max(dep_depth, current + 1)"]
+
+    PROCESS --> CYCLE{"Remaining nodes?"}
+    CYCLE -- Yes --> TARJAN["Tarjan's SCC"]
+    TARJAN --> CYCLE_DEPTH["Cycle depth = max external depth + 1"]
+    CYCLE -- No --> STATS["Compute stats"]
+
+    STATS --> CORE["Identify core modules (top N by depth)"]
+
+    style FILES fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style KAHN fill:#805ad5,stroke:#6b46c1,color:#fff
+    style TARJAN fill:#e53e3e,stroke:#c53030,color:#fff
+    style CORE fill:#d69e2e,stroke:#b7791f,color:#000
+```
+
+**Depth semantics**: Entry points (files nobody imports) have `depth = 0`. The deeper a file, the more foundational it is.
+
+**Stats output**:
+```json
+{
+  "total_files": 42,
+  "total_symbols": 234,
+  "total_edges": 156,
+  "core_modules": ["src/index.ts", "src/utils.ts", "..."]
+}
+```
+
+See [Graph Algorithms](#graph-algorithms) for detailed algorithm descriptions.
+
+### Stage I — Intermediate Map Write
+
+Writes `project_map.json` **before** AI enrichment begins. This ensures that even if enrichment crashes or is cancelled via SIGINT, the structural map is already persisted.
+
+Uses atomic write pattern with directory-level locking (see [Concurrency & Safety](#concurrency--safety)).
+
+### Stage J — AI Semantic Enrichment
+
+**File**: `src/core/graph/enricher.ts` | **Class**: `SemanticEnricher`
+
+Calls Google Gemini to generate semantic descriptions for each file. See [AI Enrichment Deep Dive](#ai-enrichment-deep-dive) for full details.
+
+### Stage K — Contract Writing
+
+**File**: `src/core/graph/contract-writer.ts` | **Class**: `ContractWriter`
+
+Writes `.semantic.md` files next to each source file. These are human-readable summaries generated from the AI enrichment data. See [Output Files](#output-files) for the template.
+
+### Stage L — Final Map Write
+
+Writes the complete `project_map.json` with AI semantic data included. Same atomic write + lock pattern as Stage I.
+
+---
+
+## Data Structures
+
+### FileNode
+
+The core unit of the map. One per scanned file.
+
+```mermaid
+classDiagram
+    class FileNode {
+        +string file
+        +string hash
+        +string language
+        +SymbolEntry[] symbols
+        +ImportEntry[] imports
+        +string[] dependents
+        +string[] dependencies
+        +number depth
+        +string last_parsed_at
+        +SemanticInfo semantic
+    }
+
+    class SymbolEntry {
+        +string name
+        +string kind
+        +number line
+        +number end_line
+        +string signature
+        +boolean exported
+    }
+
+    class ImportEntry {
+        +string source
+        +string resolved
+        +string[] symbols
+        +boolean is_external
+    }
+
+    class SemanticInfo {
+        +string overview
+        +string purpose
+        +string[] key_logic
+        +string[] usage_context
+        +string source_hash
+        +string enriched_at
+        +string model
+    }
+
+    FileNode --> "0..*" SymbolEntry
+    FileNode --> "0..*" ImportEntry
+    FileNode --> "0..1" SemanticInfo
+```
+
+### Symbol Kinds
+
+| Kind        | Source Construct                                    |
+|-------------|-----------------------------------------------------|
+| `function`  | `function name()` or `const name = () =>`          |
+| `class`     | `class Name {}`                                     |
+| `method`    | Method inside a class (stored as `ClassName.method`) |
+| `interface` | `interface Name {}`                                 |
+| `type`      | `type Name = ...`                                   |
+| `enum`      | `enum Name {}`                                      |
+| `variable`  | Named exports, const declarations                   |
+| `export`    | Re-exports                                          |
+
+### ProjectMap (Top-Level Output)
+
+```typescript
+{
+  schema_version: 1,
+  generated_at: string,       // ISO 8601
+  root: string,               // Absolute project root path
+  files: Record<string, FileNode>,
+  stats: {
+    total_files: number,
+    total_symbols: number,
+    total_edges: number,       // Total import edges
+    core_modules: string[]     // Top N files by depth
+  }
+}
+```
+
+---
+
+## Graph Algorithms
+
+### Kahn's Algorithm (Topological Sort)
+
+Used to assign **depth** to each file in the dependency graph.
+
+```
+1. Compute in-degree for every node (in-degree = number of dependents)
+2. Enqueue all nodes with in-degree 0 at depth 0
+   (these are entry points — no one imports them)
+3. While queue is not empty:
+   a. Dequeue node N
+   b. For each dependency D of N:
+      - Decrement D's in-degree
+      - D.depth = max(D.depth, N.depth + 1)
+      - If D's in-degree reaches 0, enqueue D
+4. Remaining nodes (in-degree > 0) are part of cycles
+```
+
+```mermaid
+graph TD
+    subgraph "Depth 0 (Entry Points)"
+        A["main.ts"]
+        B["cli.ts"]
+    end
+    subgraph "Depth 1"
+        C["commands/map.ts"]
+        D["commands/plan.ts"]
+    end
+    subgraph "Depth 2"
+        E["core/pipeline.ts"]
+    end
+    subgraph "Depth 3 (Core Module)"
+        F["core/config.ts"]
+    end
+
+    A --> C
+    B --> C
+    B --> D
+    C --> E
+    D --> E
+    E --> F
+
+    style A fill:#2f855a,stroke:#276749,color:#fff
+    style B fill:#2f855a,stroke:#276749,color:#fff
+    style C fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style D fill:#2b6cb0,stroke:#2c5282,color:#fff
+    style E fill:#805ad5,stroke:#6b46c1,color:#fff
+    style F fill:#d69e2e,stroke:#b7791f,color:#000
+```
+
+### Tarjan's SCC (Strongly Connected Components)
+
+Handles **circular dependencies** that Kahn's algorithm cannot process (they never reach in-degree 0).
+
+```
+1. After Kahn's completes, check for remaining nodes
+2. Run Tarjan's SCC to identify all cycles
+3. For each cycle:
+   a. Find the maximum depth among external nodes that import into the cycle
+   b. Assign all cycle members: depth = maxExternalDepth + 1
+   c. Log the full cycle path as a warning
+```
+
+```mermaid
+graph LR
+    subgraph "Cycle (SCC)"
+        X["moduleA.ts"] --> Y["moduleB.ts"]
+        Y --> Z["moduleC.ts"]
+        Z --> X
+    end
+
+    EXT["external.ts"] --> X
+    EXT2["other.ts"] --> Y
+
+    style X fill:#e53e3e,stroke:#c53030,color:#fff
+    style Y fill:#e53e3e,stroke:#c53030,color:#fff
+    style Z fill:#e53e3e,stroke:#c53030,color:#fff
+    style EXT fill:#2f855a,stroke:#276749,color:#fff
+    style EXT2 fill:#2f855a,stroke:#276749,color:#fff
+```
+
+---
+
+## AI Enrichment Deep Dive
+
+### Model & API
+
+- **Provider**: Google Generative AI (Gemini)
+- **Default model**: `gemini-1.5-flash`
+- **SDK**: `@google/generative-ai`
+
+### Authentication Flow
+
+```mermaid
+flowchart TD
+    CHECK_ENV{"GEMINI_API_KEY set?"} -- Yes --> USE_KEY["Use API key"]
+    CHECK_ENV -- No --> CHECK_OAUTH{"OAuth credentials exist?"}
+    CHECK_OAUTH -- Yes --> TOKEN["Get/refresh access token"]
+    CHECK_OAUTH -- No --> ERROR["Error: graph_ai_key_missing"]
+
+    style USE_KEY fill:#2f855a,stroke:#276749,color:#fff
+    style TOKEN fill:#2f855a,stroke:#276749,color:#fff
+    style ERROR fill:#e53e3e,stroke:#c53030,color:#fff
+```
+
+Credentials path: `~/.nomos/credentials.json`
+
+### Enrichment Per File
+
+For each file in the map:
+
+```mermaid
+flowchart TD
+    FILE["FileNode"] --> STALE{"source_hash changed?"}
+    STALE -- No --> SKIP["Skip (already enriched)"]
+    STALE -- Yes --> READ["Read file from disk"]
+    READ --> TRUNC["Truncate to max_file_chars (4000)"]
+    TRUNC --> PROMPT["Build prompt"]
+    PROMPT --> CALL["Call Gemini (structured JSON)"]
+    CALL --> VALIDATE["Validate with Zod"]
+    VALIDATE --> STORE["Store in FileNode.semantic"]
+
+    CALL -- "Fail" --> RETRY{"Attempts < 3?"}
+    RETRY -- Yes --> BACKOFF["Backoff: 2s, 4s, 8s"]
+    BACKOFF --> CALL
+    RETRY -- No --> FAIL["Record failure"]
+
+    style SKIP fill:#718096,stroke:#4a5568,color:#fff
+    style STORE fill:#2f855a,stroke:#276749,color:#fff
+    style FAIL fill:#e53e3e,stroke:#c53030,color:#fff
+```
+
+### Prompt Context
+
+Each Gemini call receives:
+- Filename and language
+- List of exported symbols
+- List of dependent files (who imports this)
+- File content (truncated at line boundary to `max_file_chars`)
+
+### Structured Output Schema
+
+```json
+{
+  "overview": "One-line summary of what this file does",
+  "purpose": "Why this file exists in the architecture",
+  "key_logic": ["Important algorithm or behavior #1", "..."],
+  "usage_context": ["How other files use this", "..."]
+}
+```
+
+### Rate Limiting
+
+- **Concurrency**: `ai_concurrency` parallel requests (default: 5)
+- **Rate limit**: `ai_requests_per_minute` (default: 14)
+- **Minimum gap**: `60000ms / ai_requests_per_minute` = ~4286ms between requests
+- **Retry backoff**: 2s, 4s, 8s (3 attempts total)
+
+### Graceful Cancellation
+
+A SIGINT handler sets a `cancellation.cancelled` flag. Between each file enrichment, the enricher checks this flag and stops early if set. The intermediate structural map (written in Stage I) is already saved.
+
+---
+
+## Incremental Processing
+
+The map command is designed for fast re-runs via incremental processing:
+
+```mermaid
+flowchart LR
+    subgraph "First Run"
+        SCAN1["Scan all files"] --> PARSE1["Parse all"]
+        PARSE1 --> ENRICH1["Enrich all"]
+    end
+
+    subgraph "Second Run (incremental)"
+        SCAN2["Scan all files"] --> HASH{"Hash changed?"}
+        HASH -- Yes --> PARSE2["Re-parse"]
+        HASH -- No --> CARRY["Carry forward FileNode"]
+        CARRY --> MERGE["Merge"]
+        PARSE2 --> MERGE
+
+        MERGE --> ENRICH2{"semantic.source_hash matches?"}
+        ENRICH2 -- Yes --> SKIP_AI["Skip AI call"]
+        ENRICH2 -- No --> RE_ENRICH["Re-enrich"]
+    end
+
+    style CARRY fill:#805ad5,stroke:#6b46c1,color:#fff
+    style SKIP_AI fill:#805ad5,stroke:#6b46c1,color:#fff
+```
+
+**What gets carried forward**:
+- Files whose SHA256 hash hasn't changed since the last map
+- Their complete `FileNode` including symbols, imports, and semantic data
+- Graph fields (dependents, dependencies, depth) are **always** recalculated
+
+**What triggers re-processing**:
+- File content change (different hash)
+- `--force` flag
+- File deletion (removed from map)
+- New file (added to map)
+
+---
+
+## Concurrency & Safety
+
+### Directory-Level Locking
+
+```mermaid
+sequenceDiagram
+    participant P1 as arc map (process 1)
+    participant FS as Filesystem
+    participant P2 as arc map (process 2)
+
+    P1->>FS: lock(output_dir/.project-map.lock)
+    FS-->>P1: Lock acquired
+    P1->>FS: Write project_map.json.tmp
+    P1->>FS: fsync(tmp)
+    P1->>FS: rename(tmp -> project_map.json)
+    P1->>FS: release lock
+
+    Note over P2,FS: P2 retries up to 10 times<br/>(200ms-2000ms backoff)
+
+    P2->>FS: lock(output_dir/.project-map.lock)
+    FS-->>P2: Lock acquired
+    P2->>FS: Write project_map.json.tmp
+    P2->>FS: fsync(tmp)
+    P2->>FS: rename(tmp -> project_map.json)
+    P2->>FS: release lock
+```
+
+**Library**: `proper-lockfile`
+**Stale timeout**: 60 seconds (accommodates slow AI enrichment writes)
+**Lock path**: `tasks-management/graph/.project-map.lock`
+
+### Atomic Write Pattern
+
+Every map write follows: **write to `.tmp`** -> **`fsync`** -> **`rename`**. This ensures readers never see a partially written file.
+
+### Import Resolution Concurrency
+
+8 concurrent workers via `p-limit` resolve imports in parallel. The `knownFiles` Set is read-only during resolution, so no synchronization is needed.
+
+---
+
+## Configuration Reference
+
+All map-related settings live under `graph` in `.nomos-config.json`:
+
+```json
+{
+  "graph": {
+    "exclude_patterns": [
+      "node_modules", "dist", "*.test.*",
+      "*.spec.*", "*.semantic.md"
+    ],
+    "ai_enrichment": true,
+    "ai_model": "gemini-1.5-flash",
+    "ai_concurrency": 5,
+    "ai_requests_per_minute": 14,
+    "max_file_chars": 4000,
+    "core_modules_count": 10,
+    "output_dir": "tasks-management/graph"
+  }
+}
+```
+
+| Field                    | Type       | Default                  | Description                              |
+|--------------------------|------------|--------------------------|------------------------------------------|
+| `exclude_patterns`       | `string[]` | See above                | Glob patterns to exclude from scanning   |
+| `ai_enrichment`          | `boolean`  | `true`                   | Enable/disable AI semantic enrichment    |
+| `ai_model`               | `string`   | `gemini-1.5-flash`       | Gemini model to use                      |
+| `ai_concurrency`         | `number`   | `5`                      | Max parallel AI requests                 |
+| `ai_requests_per_minute` | `number`   | `14`                     | Rate limit for Gemini API calls          |
+| `max_file_chars`         | `number`   | `4000`                   | Max characters sent to AI per file       |
+| `core_modules_count`     | `number`   | `10`                     | Number of core modules to identify       |
+| `output_dir`             | `string`   | `tasks-management/graph` | Directory for map output                 |
+
+---
+
+## Output Files
+
+### `project_map.json`
+
+The primary output. Full schema:
+
+```json
+{
+  "schema_version": 1,
+  "generated_at": "2026-04-10T12:34:56.789Z",
+  "root": "/absolute/project/root",
+  "files": {
+    "src/index.ts": {
+      "file": "src/index.ts",
+      "hash": "sha256:abc123...",
+      "language": "typescript",
+      "symbols": [
+        {
+          "name": "main",
+          "kind": "function",
+          "line": 10,
+          "end_line": 25,
+          "signature": "function main(): Promise<void>",
+          "exported": true
+        }
+      ],
+      "imports": [
+        {
+          "source": "./config",
+          "resolved": "src/config.ts",
+          "symbols": ["loadConfig"],
+          "is_external": false
+        }
+      ],
+      "dependents": [],
+      "dependencies": ["src/config.ts"],
+      "depth": 0,
+      "last_parsed_at": "2026-04-10T12:34:56.789Z",
+      "semantic": {
+        "overview": "Application entry point",
+        "purpose": "Bootstraps the CLI and starts execution",
+        "key_logic": ["Loads configuration", "Initializes services"],
+        "usage_context": ["Called from bin/arc"],
+        "source_hash": "sha256:abc123...",
+        "enriched_at": "2026-04-10T12:34:56.789Z",
+        "model": "gemini-1.5-flash"
+      }
+    }
+  },
+  "stats": {
+    "total_files": 42,
+    "total_symbols": 234,
+    "total_edges": 156,
+    "core_modules": ["src/config.ts", "src/utils.ts"]
+  }
+}
+```
+
+### `.semantic.md` (Contract Files)
+
+Written next to each source file. Example for `src/config.ts`:
+
+```markdown
+# config.ts -- Semantic Contract
+> Auto-generated by `arc map` -- do not edit manually.
+
+## Overview
+Loads and validates the nomos-arc CLI configuration.
+
+## Purpose
+Provides typed, validated configuration to all CLI commands.
+
+## Key Logic
+1. Walks up the filesystem to find .nomos-config.json
+2. Validates config with Zod schemas
+3. Applies default values for missing fields
+
+## Usage Context
+Used by: commands/map.ts, commands/plan.ts, commands/review.ts
+- Imported by every CLI command at startup
+- Config object is passed down through the entire pipeline
+
+---
+*Enriched at: 2026-04-10T12:34:56.789Z | Model: gemini-1.5-flash | Hash: sha256:abc123...*
+```
+
+Contracts are **skipped** if the existing `.semantic.md` already contains the current `source_hash`.
+
+---
+
+## Exit Codes
+
+| Code | Meaning                                |
+|------|----------------------------------------|
+| `0`  | Success — all files mapped and enriched |
+| `1`  | Fatal error (config, auth, parse, I/O)  |
+| `10` | Partial success — some AI enrichments failed |
+
+---
+
+## File Map (Source Code)
+
+```
+src/
+├── commands/
+│   └── map.ts                  # Command registration & CLI interface
+└── core/
+    ├── graph/
+    │   ├── pipeline.ts         # MapPipeline orchestrator (all stages)
+    │   ├── scanner.ts          # FileScanner (glob + hash + incremental)
+    │   ├── parser.ts           # ASTParser (web-tree-sitter WASM)
+    │   ├── grammar-paths.ts    # WASM grammar file resolution
+    │   ├── resolver.ts         # ImportResolver (zero-fs, knownFiles Set)
+    │   ├── builder.ts          # GraphBuilder (Kahn + Tarjan)
+    │   ├── enricher.ts         # SemanticEnricher (Gemini API)
+    │   ├── contract-writer.ts  # ContractWriter (.semantic.md)
+    │   └── map-schema.ts       # Zod schemas + read/write helpers
+    ├── config.ts               # Config loading & validation
+    ├── logger.ts               # Console + file logging
+    ├── errors.ts               # NomosError codes
+    └── auth/
+        └── manager.ts          # AuthManager (API key + OAuth)
+```
+
+---
+
+## Design Decisions & Fixes
+
+| Tag    | Location             | Decision                                                                                    |
+|--------|----------------------|---------------------------------------------------------------------------------------------|
+| BLK-1  | grammar-paths.ts     | WASM-based parsing avoids native `.node` binding portability issues                         |
+| BLK-2  | pipeline.ts          | Directory-level lockfile for atomic, serialized map writes                                  |
+| BLK-3  | builder.ts           | Reset all graph fields before building to prevent stale incremental data                    |
+| BLK-4  | builder.ts           | Kahn's BFS for correct topological depth (entry points = depth 0)                          |
+| WATCH-1| parser.ts            | web-tree-sitter WASM init is async; must await before parsing                              |
+| WATCH-3| pipeline.ts          | Lock the entire output directory, not just the map file                                     |
+| WATCH-4| resolver.ts          | knownFiles Set contract: zero filesystem calls during resolution                            |
+| AMB-1  | builder.ts           | Depth direction clarified: in-degree = dependents.length                                    |
+| AMB-2  | enricher.ts          | Read file from disk (not ScanResult) for fresh content during enrichment                   |
+| AMB-3  | parser.ts            | web-tree-sitter loads .wasm uniformly (no CJS/ESM ambiguity)                               |
+| AMB-4  | resolver.ts          | Zero filesystem calls; all existence checks via `knownFiles.has()`                          |
+| AMB-5  | contract-writer.ts   | Create parent directories before writing `.semantic.md`                                     |
+| AMB-6  | map.ts               | Exit code 10 for partial AI failure (not 2)                                                 |
+| GAP-1  | scanner.ts           | Skip files >500KB to avoid memory exhaustion                                                |
+| GAP-2  | pipeline.ts          | Write intermediate map before AI enrichment to preserve structural data on crash            |
+| GAP-3  | enricher.ts          | Cancellation flag for graceful SIGINT during enrichment                                     |
+| GAP-5  | map-schema.ts        | Forward compatibility ceiling: newer map files trigger upgrade error                        |
+| GAP-6  | builder.ts           | Tarjan's SCC algorithm for circular dependency handling                                     |