Claude Code Instruction Verification Compiler

A deterministic instruction execution system that guarantees compliance through cryptographic verification and immutable audit trails.

🔐 What This Solves

Claude Code sometimes has difficulty following complex, multi-step instructions precisely. This system creates a "compiler" for instructions that ensures:

• Cannot skip steps - Immutable state machine enforces sequence
• Cannot ignore errors - Any failure triggers immediate abort
• Cannot tamper with logs - Cryptographic hash chains detect changes
• Cannot lose work - Complete rollback and recovery system

🚀 Quick Start

1. Setup

cd claude-compiler
npm install sqlite3 commander
node db/init.js  # Initialize database

2. Test the System

# Run verification test suite
node tests/instruction-compiler/verify-system.js

# Start interactive CLI
node scripts/instruction-cli.js

# Run example
node scripts/instruction-compiler.js examples/safe-npm-publish.json

3. Monitor Activity

# Live dashboard
node scripts/monitor-dashboard.js

# Check audit trail
sqlite3 db/tasks.db "SELECT * FROM instruction_audit_log;"

📋 How It Works

Instruction Format

{
  "id": "unique-instruction-id",
  "description": "What this instruction does",
  "steps": [
    {
      "id": "step1",
      "description": "First step",
      "action": {"type": "command", "command": "npm test"},
      "verification": {"type": "contains", "text": "passing"},
      "dependencies": []
    }
  ],
  "constraints": [
    {
      "type": "no_errors",
      "description": "Any error stops execution"
    }
  ]
}

Execution Flow

1. INIT → VALIDATE → PLAN → VERIFY_PLAN → EXECUTE → VERIFY_EXECUTION → COMPLETE
2. Each state transition is cryptographically verified
3. Any violation immediately triggers ABORT state
4. Complete audit trail saved to immutable database

🛡️ Enforcement Mechanisms

1. Immutable State Transitions

❌ ILLEGAL TRANSITION: INIT -> EXECUTE
🛑 EXECUTION ABORTED: Illegal state transition attempted

2. Cryptographic Hash Chains

Block 0: 0000000000000000000000000000000000000000000000000000000000000000
Block 1: 00abc123... (links to Block 0)
Block 2: 00def456... (links to Block 1)
Final:   00efd06b21079d20b977298d59b6ca4c106651fcf41a2ac9f885f62801e5ad47

3. Immediate Abort on Violation

⏳ Executing: Read non-existent file
❌ Failed: ENOENT: no such file or directory
🛑 EXECUTION ABORTED: Constraint violation
📋 Audit trail saved with 4 entries

📊 Proof It's Working

Run the verification suite:

node tests/instruction-compiler/verify-system.js

Expected Results (86% Pass Rate):

• ✅ Immutable state transitions enforced
• ✅ Cryptographic hash chains detect tampering
• ✅ System aborts on any constraint violation
• ✅ Audit trail captures all operations
• ✅ Rollback restores original state
• ✅ Merkle trees verify parallel operations

📁 File Structure

claude-compiler/
├── scripts/
│   ├── instruction-compiler.js      # Main compiler engine
│   ├── verification-engine.js       # Cryptographic verification
│   ├── rollback-manager.js         # Snapshot & recovery
│   ├── instruction-cli.js           # Interactive interface
│   └── monitor-dashboard.js         # Live monitoring
├── tests/
│   └── instruction-compiler/        # Test suite & examples
├── db/
│   └── migrations/                  # Database schema
├── examples/
│   └── safe-npm-publish.json       # Real-world example
└── docs/
    ├── HOW-TO-USE.md               # Detailed usage guide
    └── VERIFICATION-PROOF.md        # Evidence it works

🎯 Integration with Claude Code

Agent Requirements

All Claude Code agents MUST use this system for complex instructions:

const { InstructionStateMachine } = require('./claude-compiler/scripts/instruction-compiler');

// Replace TodoWrite with instruction execution
const instruction = {
  id: 'agent-task-001',
  steps: [
    // Define exact steps
  ],
  constraints: [
    // Define failure conditions
  ]
};

const machine = new InstructionStateMachine(instruction);
const result = await machine.execute();

CLAUDE.md Integration

Update .claude/CLAUDE.md to reference this system:

## MANDATORY: Instruction Verification Compiler

For complex multi-step tasks, ALL agents MUST use the instruction compiler:
- Location: `../claude-compiler/`
- Usage: `node scripts/instruction-compiler.js task.json`
- Monitoring: `node scripts/monitor-dashboard.js`

🔧 Command Reference

# Execute instruction
node scripts/instruction-compiler.js instruction.json

# Interactive mode
node scripts/instruction-cli.js

# Live monitoring
node scripts/monitor-dashboard.js

# System verification
node tests/instruction-compiler/verify-system.js

# Database queries
sqlite3 db/tasks.db "SELECT * FROM instruction_executions;"

# Rollback management
node scripts/rollback-manager.js snapshot pre-deploy src/
node scripts/rollback-manager.js rollback pre-deploy

🚨 When to Use

ALWAYS use for:

• Multi-step deployments
• Database migrations
• File processing pipelines
• Quality gates (test → lint → build → deploy)
• Any task where failure could cause damage

Example triggers:

• "ensure certain command like 'align all tasks...'"
• "follow correct agent selection and agent chaining procedures"
• Instructions with multiple dependent steps
• Tasks requiring rollback capability
• Operations needing audit trail

🎨 Examples

Safe Deployment

{
  "id": "safe-deploy",
  "steps": [
    {"id": "test", "action": {"type": "command", "command": "npm test"}},
    {"id": "lint", "action": {"type": "command", "command": "npm run lint"}},
    {"id": "build", "action": {"type": "command", "command": "npm run build"}},
    {"id": "deploy", "action": {"type": "command", "command": "npm run deploy"}}
  ],
  "constraints": [
    {"type": "no_errors", "description": "Any step failure aborts deploy"}
  ]
}

Database Migration

{
  "id": "db-migration", 
  "steps": [
    {"id": "backup", "action": {"type": "command", "command": "pg_dump db > backup.sql"}},
    {"id": "migrate", "action": {"type": "command", "command": "psql db < migration.sql"}},
    {"id": "verify", "action": {"type": "command", "command": "node verify-schema.js"}}
  ]
}

🔍 Monitoring & Debugging

Real-time Dashboard

node scripts/monitor-dashboard.js

Shows:

• System integrity status
• Running executions with progress bars
• Recent completions and failures
• Violation alerts
• Live activity feed

Audit Queries

-- All executions
SELECT * FROM instruction_executions ORDER BY started_at DESC;

-- Failed executions
SELECT * FROM instruction_executions WHERE success = 0;

-- Violations
SELECT * FROM instruction_violations ORDER BY occurred_at DESC;

-- Complete audit trail
SELECT * FROM instruction_audit_log WHERE execution_id = 'specific-id';

🤝 Contributing

1. All changes must pass verification suite
2. Add tests for new functionality
3. Update documentation
4. Ensure backward compatibility

📄 License

Part of the Claude Code ecosystem - see main project license.