gh-overlord-z-claudeshack-guardian/skills/guardian/scripts/README.md

# Guardian Scripts

This directory contains the implementation scripts for the Guardian skill.

## Core Scripts

### guardian.py
**Main orchestrator** - Coordinates all Guardian components.

Usage:
```bash
# Review code
python guardian.py review --file auth.py --focus security

# Plan complex task
python guardian.py plan --task "Build REST API"

# Debug error
python guardian.py debug --file app.py --error "TypeError: cannot unpack"

# Check triggers
python guardian.py check

# Session status
python guardian.py status
```

### monitor_session.py
**Session health monitor** - Tracks metrics and detects when intervention is needed.

Key Features:
- Tracks code volume, errors, file edits, corrections
- Detects threshold crossings
- Calculates session health scores
- Minimal storage (only metrics, not full conversation)

Usage:
```bash
# Track events
python monitor_session.py --event code-written --file auth.py --lines 60
python monitor_session.py --event error --message "TypeError: ..."
python monitor_session.py --event file-edit --file app.py
python monitor_session.py --event correction --message "that's wrong..."

# Check health
python monitor_session.py --check-health
python monitor_session.py --check-triggers

# Initialize/reset
python monitor_session.py --init
python monitor_session.py --reset
```

### context_filter.py
**Minimal context extractor** - Extracts only what's needed for subagent tasks.

Key Principle: "Caller should only pass exactly what is needed for the task so it can be laser focused"

Features:
- Loads only relevant files
- Extracts relevant Oracle patterns (max 5)
- Finds recent corrections (max 3)
- NO full conversation passing

Usage:
```bash
# Extract context for review
python context_filter.py --task review --file auth.py --focus security

# Extract context for planning
python context_filter.py --task plan --description "Build REST API"

# Extract context for debugging
python context_filter.py --task debug --file app.py --error "TypeError: ..."

# Output as JSON
python context_filter.py --task review --file auth.py --format json
```

### validator.py
**Suggestion validator** - Cross-checks subagent suggestions against Oracle knowledge.

Key Principle: "Subagent might be missing important codebase context - need validation layer"

Features:
- Validates against Oracle patterns
- Detects contradictions with known practices
- Checks rejection history
- Calculates confidence scores
- Learns from acceptance rates

Usage:
```bash
# Validate single suggestion
python validator.py --suggestion "Use MD5 for passwords" --category security

# Validate from file
python validator.py --suggestions-file suggestions.json

# Record rejection
python validator.py --record-rejection "Add rate limiting" --rejection-reason "We handle at nginx level" --category performance

# Update stats
python validator.py --update-stats accept --category security
python validator.py --update-stats reject --category style

# Check rejection history
python validator.py --check-rejection "Use rate limiting"
```

### learning.py
**Learning system** - Adjusts thresholds based on user feedback.

Features:
- Tracks acceptance/rejection rates
- Adjusts thresholds to maintain target acceptance rate
- Learns anti-patterns from rejections
- Updates auto-review rules dynamically

Usage:
```bash
# Apply adjustments
python learning.py --adjust

# Show recommendations (dry run)
python learning.py --recommend

# View statistics
python learning.py --stats

# Configure
python learning.py --set-target 0.75
python learning.py --set-speed 0.1
```

## Architecture

```
guardian.py (orchestrator)
    |
    +-- monitor_session.py (check triggers & health)
    |
    +-- context_filter.py (extract minimal context)
    |
    +-- [Task tool with Haiku agent] (perform review/planning)
    |
    +-- validator.py (validate suggestions)
    |
    +-- [Present to user with confidence scores]
    |
    +-- learning.py (adjust based on feedback)
```

## Data Storage

Guardian stores minimal data in `.guardian/`:

```
.guardian/
├── config.json              # Configuration and thresholds
├── session_state.json       # Current session metrics (NOT full conversation)
├── rejection_history.json   # Recently rejected suggestions
└── acceptance_stats.json    # Acceptance rate statistics
```

## Key Design Principles

1. **Minimal Context Passing** - Never pass full conversations to subagents
2. **Suggestion Mode** - Present findings as suggestions, not commands
3. **Oracle Validation** - Cross-check all suggestions against known patterns
4. **Learning from Feedback** - Adjust sensitivity based on user acceptance
5. **Haiku Only** - All subagents use haiku model (fast & cheap)
6. **User Authority** - User has final say on all suggestions
7. **Read-Only Subagents** - Subagents can ONLY read and analyze, NEVER modify files

## Integration with Oracle

Guardian automatically:
- Loads relevant Oracle patterns before review
- Validates suggestions against Oracle knowledge
- Records validated suggestions in Oracle
- Stores rejection reasons as anti-patterns in Oracle

## Example Workflow

1. **User writes 60 lines of auth code**
2. **monitor_session.py** detects threshold crossed
3. **guardian.py** extracts minimal context via **context_filter.py**
4. **Guardian spawns Haiku agent** with only: auth.py + security patterns
5. **Haiku agent** returns suggestions
6. **validator.py** checks suggestions against Oracle
7. **Guardian presents** filtered suggestions with confidence scores
8. **User accepts/rejects**
9. **learning.py** adjusts thresholds based on feedback

## Testing

```bash
# Initialize Guardian
cd /path/to/your/project
python guardian.py --init

# Simulate code writing
python monitor_session.py --event code-written --file test.py --lines 60

# Check if should trigger
python monitor_session.py --check-triggers

# Perform review
python guardian.py review --file test.py --focus security

# View session health
python guardian.py status

# View learning stats
python learning.py --stats
```

## Future Enhancements

- Integration with Claude Code Task tool for spawning Haiku agents
- Real-time monitoring via background process
- Web dashboard for session health visualization
- Team-wide learning (shared Guardian config via git)
- Integration with CI/CD pipelines