@codmir/governor

Governor system for auditing code changes with full AI context.

Concept

Governor is different from a traditional PR review:

| Traditional PR | Governor Audit | |----------------|----------------| | Code changes only | Code + AI reasoning + conversation + logs | | Reviewer guesses intent | Intent is documented | | Post-hoc review | Present during development | | Manual review | AI-assisted analysis |

Governor = Present during each process (proactive) Overseer = Reviews after completion (reactive)

Features

• Audit Changes: Analyze code changes between any two commits
• Full Context: Include conversation history, AI reasoning, execution logs
• AI Analysis: Claude-powered review finding security, performance, logic issues
• Session Tracking: Monitor work as it happens, not just after
• CLI Support: Quick audits from command line
• Tool Integration: Register audit tools with AI agents

Installation

pnpm add @codmir/governor

Quick Start

CLI Audit

# Audit recent changes
codmir-agent audit

# Audit specific range
codmir-agent audit --from v1.0.0 --to HEAD

# Audit with context file
codmir-agent audit --context-file conversation.json

Programmatic Usage

import { createAuditService, createGovernorSession } from '@codmir/governor';

// Create audit service
const auditService = createAuditService({
  repoPath: '/path/to/repo',
  apiKey: process.env.ANTHROPIC_API_KEY,
});

// Quick audit
const audit = await auditService.quickAudit({
  from: 'HEAD~10',
  to: 'HEAD',
});

console.log('Findings:', audit.findings.length);
console.log('Recommendation:', audit.summary?.recommendation);

Governor Session (Track Work in Progress)

import { createGovernorSession, getGovernorSessionManager } from '@codmir/governor';

// Start session when agent begins work
const session = createGovernorSession({
  taskId: 'task-123',
  baseCommit: 'abc123',
});

// Track conversation
const manager = getGovernorSessionManager();
manager.addConversationTurn(session.id, 'user', 'Please fix the login bug');
manager.addConversationTurn(session.id, 'assistant', 'I will fix the authentication issue...');

// Track reasoning
manager.addReasoning(session.id, {
  target: { file: 'src/auth.ts', startLine: 42 },
  intent: 'Fix null check on user token',
  approach: 'Added optional chaining to prevent crash',
  tradeoffs: ['Slightly less strict typing'],
});

// Track execution
manager.addLog(session.id, 'file_write', 'Modified src/auth.ts');
manager.addLog(session.id, 'command', 'npm test - all tests passing');

// Get context for audit
const context = manager.getContext(session.id);

AI Agent Tools

import { AUDIT_TOOL_DEFINITIONS, createAuditToolExecutor } from '@codmir/governor';

// Register tools with Claude
const tools = AUDIT_TOOL_DEFINITIONS;

// Execute tool calls
const executor = createAuditToolExecutor(auditService, {
  agentId: 'agent-123',
  agentName: 'Code Assistant',
});

const result = await executor.execute('audit_changes', {
  from_commit: 'HEAD~5',
  to_commit: 'HEAD',
  min_severity: 'medium',
});

Audit Lifecycle

Created → Analyzing → Reviewing → Approved/Rejected → Merged

1. Created: Audit record created with target commits
2. Analyzing: AI is analyzing changes
3. Reviewing: Analysis complete, awaiting human/agent review
4. Approved/Rejected: Decision made
5. Merged: Changes merged (optional tracking)

Finding Categories

• security - Security vulnerabilities
• performance - Performance issues
• logic - Logic errors or bugs
• style - Code style issues
• documentation - Missing/incorrect docs
• testing - Test coverage issues
• architecture - Architectural concerns
• dependency - Dependency issues
• compatibility - Compatibility problems
• accessibility - Accessibility issues

Finding Severities

• critical - Must fix immediately
• high - Should fix before merge
• medium - Should fix soon
• low - Nice to fix
• info - Informational note

Events

Subscribe to governor events:

// governor.audit.created
// governor.audit.started
// governor.audit.completed
// governor.audit.failed
// governor.audit.approved
// governor.audit.rejected
// governor.audit.merged
// governor.finding.added
// governor.finding.resolved
// governor.context.updated
// governor.reasoning.added

License

MIT