jay-code/.claude/templates/CLAUDE_VERIFIED.md

Streamlined AI CLI orchestration engine with mathematical rigor and enterprise-grade reliability

# Claude Code Configuration - Truth-Verified Development

## 🛡️ Verification & Truth Scoring System

### Status: [ENABLED/DISABLED]
Current Mode: **PASSIVE** | Truth Threshold: **0.80**

### Quick Enable
```bash
# Enable verification (non-breaking, opt-in)
npx jay-code verify --enable

# Set verification mode
npx jay-code verify --mode strict  # passive|active|strict

# Set truth threshold
npx jay-code verify --threshold 0.95
```

## 🎯 Truth Scoring Integration

### How It Works
Every agent action is automatically scored for truthfulness:
- **Claims** vs **Reality** comparison
- **Evidence-based** scoring (tests, lint, types, build)
- **Persistent memory** tracking
- **Historical reliability** calculation

### Check Truth Scores
```bash
# Current agent score
npx jay-code truth score [agent-id]

# Agent reliability over time
npx jay-code truth reliability [agent-id]

# Full truth report
npx jay-code truth report --format markdown
```

## 🚨 CRITICAL: Concurrent Execution Rules

**WITH VERIFICATION**: All operations remain concurrent with truth scoring

### Verified Batch Operations
```javascript
// Everything in ONE message with verification
[Single Message]:
  - TodoWrite { todos: [10+ todos], verify: true }
  - Task("Agent 1", { verify: true }), Task("Agent 2", { verify: true })
  - Read + Verify, Write + Verify, Edit + Verify
  - Bash("npm test") + Truth Score
```

## 🤖 Agent Verification Hooks

### Each Agent Now Includes:
```javascript
{
  type: "coder",
  verification: {
    pre_task: "snapshot + baseline tests",
    during_task: "incremental validation",
    post_task: "truth score calculation",
    on_claim: "evidence gathering"
  }
}
```

### Verification-Enhanced Agents (54 Total)
All existing agents now support optional verification:

| Agent | Truth Features |
|-------|---------------|
| coder | Code compilation + test verification |
| reviewer | Claim validation + cross-checking |
| tester | Test execution + coverage truth |
| planner | Feasibility verification |
| production-validator | Real deployment verification |

## 📦 NPX Commands with Verification

### Standard Commands (Backward Compatible)
```bash
# Works exactly as before
npx jay-code sparc run dev "build feature"

# Add --verify for truth scoring
npx jay-code sparc run dev "build feature" --verify

# Set verification level
npx jay-code sparc run dev "build feature" --verify=strict
```

### New Verification Commands
```bash
# Verification control
npx jay-code verify --enable                # Enable system
npx jay-code verify --status                # Check status
npx jay-code verify --mode [passive|active|strict]  # Set mode
npx jay-code verify --threshold 0.95        # Set threshold

# Truth scoring
npx jay-code truth score [agent-id]         # Get score
npx jay-code truth history [agent-id]       # View history
npx jay-code truth reliability [agent-id]   # Check reliability
npx jay-code truth report                   # Generate report

# Checkpoints & rollback
npx jay-code checkpoint create              # Manual checkpoint
npx jay-code checkpoint list                # List checkpoints
npx jay-code rollback [checkpoint-id]       # Rollback to checkpoint
```

## 🔧 MCP Tool Integration

### Enhanced MCP Tools (Backward Compatible)
```javascript
// Existing tools work as before
mcp__jay-code__swarm_init { topology: "mesh" }

// Add verification (optional)
mcp__jay-code__swarm_init { 
  topology: "mesh",
  verification: { enabled: true, mode: "strict" }
}

// New verification-specific tools
mcp__jay-code__truth_score {
  agent_id: "coder-1",
  claim: "All tests pass",
  evidence: { test_results: {...} }
}

mcp__jay-code__verify_handoff {
  from_agent: "coder-1",
  to_agent: "tester-1",
  require_acceptance: true
}
```

## 💾 Memory-Based Truth Persistence

### Automatic Storage
```
.jay-code/memory/truth-scores/
├── coder-1_task-123_1234567890.json
├── tester-1_task-124_1234567891.json
└── reviewer-1_task-125_1234567892.json
```

### Memory Integration
```javascript
// Truth scores automatically stored via memory_usage
mcp__jay-code__memory_usage {
  action: "store",
  namespace: "truth_scores",
  key: "agent_task_score",
  value: { score: 0.95, evidence: {...} },
  truth_metadata: { verified: true }  // NEW
}
```

## 📊 Verification Modes

### Passive Mode (Default)
- Logs truth scores
- No enforcement
- Zero performance impact
- Good for initial adoption

### Active Mode
- Warns on low scores
- Highlights discrepancies
- Suggests improvements
- Non-blocking

### Strict Mode
- Blocks on verification failure
- Automatic rollback
- Requires 95%+ truth score
- Maximum reliability

## 🔄 Progressive Adoption

### Phase 1: Start Passive
```bash
npx jay-code verify --enable --mode passive
# Monitor truth scores without disruption
```

### Phase 2: Active Warning
```bash
npx jay-code verify --mode active
# Get warnings but continue working
```

### Phase 3: Strict Enforcement
```bash
npx jay-code verify --mode strict --threshold 0.95
# Full verification with rollback
```

## 📈 Monitoring & Metrics

### Dashboard
```bash
npx jay-code dashboard --verification
```

Shows:
- Truth scores by agent
- Verification success rate
- Rollback frequency
- Performance impact
- Reliability trends

### Reports
```bash
# Generate truth report
npx jay-code truth report --format markdown > truth-report.md

# CI/CD integration
npx jay-code truth report --format json | jq '.agents'
```

## 🔗 GitHub Integration

### GitHub Actions
```yaml
- name: Run with Verification
  run: |
    npx jay-code@alpha verify --enable
    npx jay-code@alpha sparc run dev "$TASK" --verify
    npx jay-code@alpha truth report
  env:
    VERIFICATION_MODE: strict
    TRUTH_THRESHOLD: 0.95
```

### PR Verification
```yaml
- name: Verify PR
  run: npx jay-code@alpha verify --pr ${{ github.event.pull_request.number }}
```

## ⚡ Performance Tips with Verification

1. **Selective Verification** - Verify critical paths only
2. **Async Scoring** - Truth scores calculated in background
3. **Cache Results** - Reuse verification for unchanged code
4. **Batch Verification** - Verify multiple agents together

## 🚀 Migration Guide

### For Existing Projects
```bash
# 1. Install verification (non-breaking)
npx jay-code@alpha init --add-verification

# 2. Start in passive mode
npx jay-code verify --enable --mode passive

# 3. Monitor for 1 week
npx jay-code truth report

# 4. Gradually increase enforcement
npx jay-code verify --mode active  # After 1 week
npx jay-code verify --mode strict  # After 2 weeks
```

## 📝 Configuration

### .claude/config/verification.json
```json
{
  "enabled": false,          // Start disabled
  "mode": "passive",         // passive|active|strict
  "truth_threshold": 0.80,   // Minimum acceptable score
  "rollback_enabled": false, // Auto-rollback on failure
  "weights": {
    "tests": 0.40,
    "lint": 0.20,
    "types": 0.20,
    "build": 0.20
  }
}
```

## 🎯 Benefits of Verification

1. **Trustworthy Output** - Know when AI claims are accurate
2. **Reduced Human Verification** - 75% less manual checking
3. **Automatic Rollback** - Never break working code
4. **Agent Improvement** - Agents learn from truth scores
5. **Audit Trail** - Complete verification history

## 🔍 Troubleshooting

### Low Truth Scores
```bash
# Check what's failing
npx jay-code truth diagnose [agent-id]

# View detailed evidence
npx jay-code truth evidence [task-id]

# Retrain agent
npx jay-code agent retrain [agent-id] --focus verification
```

### Performance Impact
```bash
# Measure overhead
npx jay-code benchmark --with-verification

# Optimize verification
npx jay-code verify optimize

# Selective verification
npx jay-code verify --only-critical
```

---

**Remember**: Verification is **opt-in** and **backward compatible**. Start passive, measure impact, then increase enforcement as confidence grows.

## Original Jay-Code Features
[All existing Jay-Code features continue to work as before...]