npm package: @codmir/governor
Description: Governor system for auditing code changes with AI reasoning, conversation history, and execution logs
Latest version: 1.0.0

# @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

```bash
pnpm add @codmir/governor
```

## Quick Start

### CLI Audit

```bash
# 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

```typescript
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)

```typescript
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

```typescript
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:

```typescript
// 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