Knowledge Graph

# Error Handling - Knowledge Graph

Comprehensive error handling strategies and behaviors for Knowledge Graph operations.

## Error Types

### 1. File Not Found

**Scenario:** KG file doesn't exist at expected path.

**Behavior:**
- Return empty KG structure
- Message: "No existing knowledge graph, will create new"
- Action: Continue with empty KG, will be created on first update

**Empty KG Structure:**
```json
{
  "metadata": {
    "spec_id": null,
    "feature_name": null,
    "created_at": null,
    "updated_at": null,
    "version": "1.0",
    "analysis_sources": []
  },
  "codebase_context": {
    "project_structure": {},
    "technology_stack": []
  },
  "patterns": {
    "architectural": [],
    "conventions": []
  },
  "components": {
    "controllers": [],
    "services": [],
    "repositories": [],
    "entities": [],
    "dtos": []
  },
  "provides": [],
  "apis": {
    "internal": [],
    "external": []
  },
  "integration_points": []
}
```

**When this occurs:**
- First time running spec-to-tasks for a spec
- KG was deleted
- Incorrect path provided

**User impact:** None (normal operation)

---

### 2. Invalid JSON

**Scenario:** KG file exists but contains invalid JSON.

**Behavior:**
- Raise error
- Message: "Knowledge graph corrupted at {path}"
- Action: Ask user: "Recreate from codebase analysis?"

**Detection:**
```python
try:
    kg_data = json.load(kg_file)
except json.JSONDecodeError as e:
    raise KnowledgeGraphError(
        f"Knowledge graph corrupted at {path}: {str(e)}"
    )
```

**Recovery options:**
1. Recreate from codebase analysis
2. Restore from backup (if available)
3. Manual repair (advanced users)

**User impact:** High (cannot use existing KG)

---

### 3. Merge Conflicts

**Scenario:** Concurrent updates to KG cause merge conflicts.

**Behavior:**
- Preserve existing values, add new with timestamps
- Message: "Merged X new findings into existing knowledge graph"

**Merge Strategy:**
- **Arrays**: Append new items (check for duplicates by ID)
- **Objects**: Deep merge, preserve existing keys
- **Metadata**: Always update timestamps and sources

**Example merge:**
```python
def merge_kg(existing, updates):
    # Arrays: append if not duplicate
    for key in ['patterns', 'components', 'apis']:
        for item in updates[key]:
            if item not in existing[key]:
                existing[key].append(item)

    # Objects: deep merge
    for key in ['codebase_context']:
        existing[key].update(updates[key])

    # Metadata: always update
    existing['metadata']['updated_at'] = datetime.now().isoformat()

    return existing
```

**Detection:**
- Duplicate IDs in arrays
- Conflicting values for same key

**Prevention:**
- Use atomic file writes
- Add source tracking to updates
- Use optimistic locking

---

### 4. Write Failure

**Scenario:** Cannot write KG file (permissions, disk full, etc.).

**Behavior:**
- Log error, continue without caching
- Message: "Cannot write knowledge graph, continuing without cache"

**Detection:**
```python
try:
    with open(kg_path, 'w') as f:
        json.dump(kg_data, f, indent=2)
except (IOError, OSError) as e:
    logger.error(f"Cannot write knowledge graph: {str(e)}")
    # Continue without caching
    return None
```

**Impact:**
- No caching benefits
- Must re-explore codebase next time
- Performance degradation

**Recovery:**
- Fix permissions
- Free disk space
- Retry write operation

---

### 5. Path Validation Errors

**Scenario:** Invalid path provided for KG operations.

**Behavior:**
- Raise error
- Message: "Invalid knowledge graph path: {path}"

**Validation rules:**
- Path must start with `docs/specs/`
- Path must not contain `..` (parent directory)
- Path must be within project root

**Example:**
```python
def validate_kg_path(path):
    # Must start with docs/specs/
    if not path.startswith("docs/specs/"):
        raise ValueError(f"Invalid KG path: {path}")

    # No path traversal
    if ".." in path:
        raise ValueErro