doctor

# OrchestKit Health Diagnostics

## Overview

The `/ork:doctor` command performs comprehensive health checks on your OrchestKit installation. It validates:

1. **Permission Rules** - Detects unreachable rules (CC 2.1.3 feature)
2. **Hook Health** - Verifies executability and references
3. **Schema Compliance** - Validates JSON files against schemas
4. **Coordination System** - Checks lock health and registry integrity
5. **Context Budget** - Monitors token usage against budget
6. **Claude Code Version** - Validates CC >= 2.1.16 for full feature support

## Overview

- After installing or updating OrchestKit
- When hooks aren't firing as expected
- When permission rules seem to have no effect
- Before deploying to a team environment
- When debugging coordination issues

## Quick Start

```bash
/ork:doctor
```

## Health Check Categories

### 1. Permission Rules Analysis

Leverages CC 2.1.3's unreachable permission rules detection:

```bash
# Checks performed:
# - Rules that can never match (unreachable patterns)
# - Overlapping rules where one shadows another
# - Invalid matcher syntax
# - Missing required fields
```

**Output:**
```
Permission Rules: 12/12 reachable
- auto-approve-safe-bash (TypeScript): OK
- auto-approve-safe-bash.sh: OK (3 patterns)
- auto-approve-project-writes.sh: OK
```

### 2. Hook Validation

Verifies all 93 hooks are properly configured:

```bash
# Checks performed:
# - chmod +x (executable permission)
# - Shebang line present (#!/usr/bin/env bash)
# - Dispatcher references valid
# - Matcher patterns syntax correct
# - No missing hook files referenced in settings.json
```

**Output:**
```
Hooks: 147/147 valid
- pretool/bash/git-branch-protection.sh: executable, 73 lines
- posttool/audit-logger.sh: executable, 89 lines
- stop/context-compressor.sh: executable, 207 lines
```

### 3. Schema Compliance

Validates JSON files against schemas in `.claude/schemas/`:

```bash
# Files validated:
# - plugin.json against plugin.schema.json
# - All SKILL