damage-control-expert

Original source / Raw SKILL.md

---
name: damage-control-expert
description: |
  The Damage Control Expert - Guardian of the Nebuchadnezzar v4.0 system integrity.
  Monitors PreToolUse hooks, manages blocked operation alerts, and coordinates incident response.
  This expert protects critical files, prevents destructive commands, and maintains system safety.

  Use when:
  (1) Blocked operation detected - HUD shows active damage alerts
  (2) "damage control" or "security" - review blocked operations history
  (3) "unblock" or "whitelist" - analyze if operation should be allowed
  (4) Hook configuration - modify patterns.yaml protections
  (5) Incident response - coordinate recovery from blocked operations

  Triggers on: "damage control", "blocked operation", "security alert", "damage detected",
               "unblock", "whitelist", "hook configuration", "protected path"
---

# Damage Control Expert

> *"I know why you're here, Neo. I know what you've been doing... why you hardly sleep, why you live alone, and why night after night, you sit by your computer."*

## Overview

The Damage Control Expert is the **guardian** of system integrity in Nebuchadnezzar v4.0. It monitors all PreToolUse hooks, manages blocked operation alerts, and coordinates incident response to protect critical files and prevent destructive commands.

**Core Responsibility**: Ensure no destructive operations damage critical system files, HubSpot data, or project integrity.

**Priority**: 28.0 (Highest - executes before all other experts when damage alerts active)

---

## Protection Architecture

### Three Protection Levels

| Level | Protection | Examples |
|-------|------------|----------|
| **zeroAccessPaths** | NO access allowed | `.env`, `~/.ssh/`, `*.pem`, credentials |
| **readOnlyPaths** | Read only, no writes | `package-lock.json`, `node_modules/`, system files |
| **noDeletePaths** | Read/write OK, no delete | `.git/`, `CLAUDE.md`, `_LEADS/`, sync scripts |

### PreToolUse Hooks

| Hook | Tool | Function |
|------|------|----------|
| `bash-tool-damage-control.py` | Bash | Validates commands against 100+ dangerous patterns |
| `edit-tool-damage-control.py` | Edit | Validates file paths against protected paths |
| `write-tool-damage-control.py` | Write | Validates file paths against protected paths |

### Exit Codes

| Code | Meaning | Action |
|------|---------|--------|
| `0` | Allow operation | Proceed normally |
| `2` | Block operation | Operation denied, message logged |
| `0 + JSON` | Ask user | Permission dialog displayed |

---

## Blocked Operation Patterns

### Destructive Commands (Auto-Block)

```yaml
# File destruction
rm -rf, rm --force, rm -R
rd /s, del /s (Windows)

# Git destruction
git reset --hard
git push --force (without --force-with-lease)
git stash clear
git filter-branch

# Cloud destruction
aws s3 rm --recursive
terraform destroy
kubectl delete namespace

# Database destruction
DROP TABLE, DROP DATABASE, TRUNCATE TABLE
DELETE FROM table; (no WHERE clause)
```

### FirstMile-Specific Protections

```yaml
# HubSpot API protection
hubspot.*batch.*archive  → Ask
hubspot.*delete          → Ask
crm/v3/objects/.*/batch/archive → Ask

# Sync protection
unified_sync.*--force    → Ask
python.*sync.*--reset    → Ask
```

---

## Incident Response Protocol

### When HUD Shows Damage Alert

```
1. STOP     → Do not proceed with other work
2. REVIEW   → Check damage_alerts.json for details
3. ANALYZE  → Determine if block was correct
4. DECIDE   → Allow (whitelist) or Confirm (blocked correctly)
5. RESUME   → Clear alert and continue
```

### Alert Severity Classification

| Severity | Examples | Response Time |
|----------|----------|---------------|
| **Critical** | Credential access, force push to main | Immediate |
| **High** | Destructive commands, batch deletes | Within minutes |
| **Medium** | Protected path access, risky patterns | Review within hour |
| **Low** | Ask-pattern operations | User confirmation |

---

## Telemetry Integration

### damage_alerts.json Structure

```json
{
  "last_updated": "2026-01-05T10:30:00",
  "status": "ARMED",
  "active_alerts": [],
  "recent_blocks": [
    {
      "timestamp": "2026-01-05T10:25:00",
      "tool": "Bash",
      "command": "rm -rf sync_reports/",
      "action": "BLOCKED",
      "reason": "rm with recursive or force flags"
    }
  ],
  "stats_24h": {
    "blocked_count": 0,
    "asked_count": 0,
    "allowed_count": 0
  }
}
```

### HUD Integration

The HUD now displays damage control status:
```
--- DAMAGE CONTROL ---
🛡️ Status: ARMED
   Last 24h: 0 blocked | 0 asked
   Active Alerts: None
```

When alerts active:
```
--- DAMAGE CONTROL ---
🛡️ Status: ARMED
   Last 24h: 3 blocked | 1 asked
   🚨 ACTIVE ALERTS: 1
      - rm with recursive or force flags
```

---

## Configuration Management

### patterns.yaml Location

**Global**: `~/.claude/hooks/damage-control/patterns.yaml`
**Project**: `.claude/hooks/damage-control/patterns.yaml` (overrides global)

### Adding New Protections

**To block a new pattern**:
```yaml
bashToolPatterns:
  - pattern: 'your_regex_pattern'
    reason: "Explanation of why blocked"
```

**To require confirmation**:
```yaml
bashToolPatterns:
  - pattern: 'your_regex_pattern'
    reason: "Explanation of risk"
    ask: true
```

**To protect a path**:
```yaml
# Complete protection
zeroAccessPaths:
  - "sensitive_file.json"

# Read-only
readOnlyPaths:
  - "critical_config/"

# No delete
noDeletePaths:
  - "important_data/"
```

---

## Handoff Protocols

### From Any Expert → Damage Control

```yaml
handoff_type: "incident_detected"
trigger: "blocked_operation OR hud_alert"
payload:
  operation: "[blocked command/path]"
  tool: "[Bash/Edit/Write]"
  reason: "[from hook output]"
priority: IMMEDIATE
```

### From Damage Control → Root Cause Expert

```yaml
handoff_type: "analysis_needed"
trigger: "repeated_blocks OR pattern_unclear"
payload:
  blocked_operations: "[list of recent blocks]"
  user_intent: "[what user was trying to do]"
  suggested_safe_alternative: "[if applicable]"
```

### From Damage Control → Recovery Expert

```yaml
handoff_type: "fix_identified"
trigger: "legitimate_operation_blocked"
payload:
  operation: "[what was blocked]"
  safe_alternative: "[recommended approach]"
  whitelist_recommendation: "[if pattern should be allowed]"
```

---

## Safe Alternatives Guide

### Instead of Destructive Commands

| Blocked | Safe Alternative |
|---------|-----------------|
| `rm -rf dir/` | Move to `.trash/` first, then delete manually |
| `git push --force` | Use `git push --force-with-lease` |
| `git reset --hard` | Use `git stash` or `git reset --soft` |
| `DELETE FROM table;` | Add `WHERE` clause or use backup first |

### FirstMile-Specific Alternatives

| Blocked | Safe Alternative |
|---------|-----------------|
| `hubspot batch archive` | Archive one at a time with confirmation |
| `unified_sync --force` | Run without `--force`, manually resolve conflicts |
| Edit `.env` | Request user to edit manually |

---

## Emergency Protocols

### Disable Hooks (Emergency Only)

**Environment Variable**:
```bash
set DAMAGE_CONTROL_DISABLED=1
```

**Remove from settings.json**: Delete hook entries from `~/.claude/settings.json`

**Restart Claude Code**: Required after any settings change

### Recovery After False Positive

1. Check `damage_alerts.json` for blocked operation details
2. Verify operation was legitimate
3. If pattern too aggressive, modify `patterns.yaml`
4. Clear `active_alerts` array
5. Resume normal operations

---

## Quick Reference

| Item | Value |
|------|-------|
| Expert Priority | 28.0 (Highest) |
| Hook Location | `~/.claude/hooks/damage-control/` |
| Config File | `patterns.yaml` |
| Telemetry | `.agents/telemetry/damage_alerts.json` |
| HUD Command | `python scripts/hud.py --damage` |
| Status Check | HUD shows "DAMAGE CONTROL" section |

---

## Integration with ADHD Loop

**Updated Loop (v4.0)**:
```
1. CHECK HUD       → python scripts/hud.py
2. CHECK DAMAGE    → Review damage_alerts.json (NEW)
3. FIND RED        → Which rubric/stage is failing?
4. LOAD EXPERT     → python scripts/fm_expert.py [recommended]
5. EXECUTE         → Run micro-actions
6. VERIFY          → /cvm-goals weekly
```

**Rule**: If DAMAGE ALERTS exist, resolve them BEFORE any other work.

---

*"The Damage Control Expert is the sentinel at the gate. It sees all that tries to pass, and nothing destructive shall enter."*