# Code Audit Governance
**Version:** 0.6.0
**Status:** Implemented
**GitHub Issue:** [#8](https://github.com/earchibald/amicus-mcp/issues/8)
## Overview
The Code Audit Governance feature ensures that agents submit proposed file changes for review by a code reviewer agent before execution. This adds a governance layer to multi-agent coordination, preventing unreviewed code changes and promoting code quality.
## Workflow
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Developer │ │ Code Audit │ │ Code Reviewer │
│ Agent │ │ Queue │ │ Agent │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ submit_code_audit_ │ │
│ request() │ │
│──────────────────────>│ │
│ │ │
│ returns audit_id │ │
│<──────────────────────│ │
│ │ │
│ │ get_pending_audits() │
│ │<──────────────────────│
│ │ │
│ │ returns audit list │
│ │──────────────────────>│
│ │ │
│ │ approve_code_audit() │
│ │<──────────────────────│
│ │ │
│ get_audit_status() │ │
│──────────────────────>│ │
│ │ │
│ status: APPROVED │ │
│<──────────────────────│ │
│ │ │
│ (proceed with │ │
│ file changes) │ │
│ │ │
```
## MCP Tools
### submit_code_audit_request
Submit a code audit request before making file changes.
**Parameters:**
- `requesting_agent` (string, required): ID of the agent requesting the audit
- `files` (list[string], required): List of file paths that will be modified
- `description` (string, required): Description of what changes will be made and why
- `proposed_changes` (string, required): The actual changes (diff, code snippet, or description)
- `priority` (string, optional): Priority level - "low", "medium" (default), "high"
**Returns:** Audit ID and status message
**Example:**
```python
submit_code_audit_request(
requesting_agent="Node-Dev-001",
files=["src/utils.py", "src/main.py"],
description="Refactoring utility functions for better performance",
proposed_changes="def process_data(data):\n # New optimized implementation\n return [x * 2 for x in data]",
priority="medium"
)
# Returns: "Code audit request submitted: audit-a1b2c3d4\nFiles: src/utils.py, src/main.py\nStatus: PENDING - Awaiting reviewer approval.\nPriority: MEDIUM"
```
### get_pending_audits
Get all pending code audit requests awaiting review.
**Parameters:**
- `reviewer_agent` (string, optional): Filter audits assigned to specific reviewer
**Returns:** Formatted list of pending audits
**Example:**
```python
get_pending_audits()
# Returns:
# 📋 Pending Code Audits
# ============================================================
#
# 🔍 Audit ID: audit-a1b2c3d4
# Priority: MEDIUM
# Requesting Agent: Node-Dev-001
# Files: src/utils.py, src/main.py
# Description: Refactoring utility functions for better performance
# Age: 2.5m
# Proposed Changes:
# def process_data(data):
# # New optimized implementation
# return [x * 2 for x in data]
#
# 📊 Total pending: 1
```
### approve_code_audit
Approve a pending code audit request.
**Parameters:**
- `audit_id` (string, required): The ID of the audit to approve
- `reviewer_agent` (string, required): ID of the agent approving the audit
- `feedback` (string, optional): Optional feedback or comments
**Returns:** Success message or error
**Constraints:**
- Cannot approve your own audit request
- Audit must be in "pending" status
**Example:**
```python
approve_code_audit(
audit_id="audit-a1b2c3d4",
reviewer_agent="Node-Reviewer-001",
feedback="Looks good! Consider adding a docstring."
)
# Returns: "✅ Code audit 'audit-a1b2c3d4' APPROVED by Node-Reviewer-001.\nRequesting agent Node-Dev-001 may proceed with changes to: src/utils.py, src/main.py\nFeedback: Looks good! Consider adding a docstring."
```
### reject_code_audit
Reject a pending code audit request.
**Parameters:**
- `audit_id` (string, required): The ID of the audit to reject
- `reviewer_agent` (string, required): ID of the agent rejecting the audit
- `feedback` (string, required): Feedback explaining why the audit was rejected
**Returns:** Success message or error
**Constraints:**
- Cannot reject your own audit request
- Feedback is required
- Audit must be in "pending" status
**Example:**
```python
reject_code_audit(
audit_id="audit-a1b2c3d4",
reviewer_agent="Node-Reviewer-001",
feedback="The list comprehension could cause memory issues with large datasets. Please use a generator instead."
)
# Returns: "❌ Code audit 'audit-a1b2c3d4' REJECTED by Node-Reviewer-001.\nRequesting agent Node-Dev-001 must address feedback and resubmit.\nFeedback: The list comprehension could cause memory issues with large datasets. Please use a generator instead."
```
### get_audit_status
Get the status and details of a specific code audit request.
**Parameters:**
- `audit_id` (string, required): The ID of the audit to check
**Returns:** Audit details and status
**Example:**
```python
get_audit_status("audit-a1b2c3d4")
# Returns:
# ✅ Code Audit: audit-a1b2c3d4
# ==================================================
# Status: APPROVED
# Requesting Agent: Node-Dev-001
# Files: src/utils.py, src/main.py
# Priority: MEDIUM
# Description: Refactoring utility functions for better performance
# Created: 5.2 minutes ago
# Reviewed By: Node-Reviewer-001
# Reviewed: 2.1 minutes ago
# Feedback: Looks good! Consider adding a docstring.
#
# Proposed Changes:
# def process_data(data):
# # New optimized implementation
# return [x * 2 for x in data]
#
# ✅ APPROVED - You may proceed with the file changes.
```
### list_code_audits
List all code audits with optional filtering.
**Parameters:**
- `status_filter` (string, optional): Filter by status - "pending", "approved", "rejected"
- `agent_filter` (string, optional): Filter by requesting or reviewing agent ID
- `limit` (int, optional): Maximum number of audits to return (default: 20)
**Returns:** Formatted list of code audits
**Example:**
```python
list_code_audits(status_filter="approved", limit=10)
# Returns:
# 📋 Code Audits
# ============================================================
# Summary: 2 pending, 5 approved, 1 rejected
#
# ✅ audit-a1b2c3d4 | Node-Dev-001 | src/utils.py, src/main.py | 5.2m
# ✅ audit-e5f6g7h8 | Node-Dev-002 | src/config.py | 12.3m
```
## State Schema
Code audits are stored in the `code_audits` field of state.json:
```json
{
"code_audits": {
"audit-a1b2c3d4": {
"id": "audit-a1b2c3d4",
"requesting_agent": "Node-Dev-001",
"reviewer_agent": "Node-Reviewer-001",
"files": ["src/utils.py", "src/main.py"],
"description": "Refactoring utility functions",
"proposed_changes": "def process_data(data): ...",
"priority": "medium",
"status": "approved",
"feedback": "Looks good!",
"created_at": 1770097411.123,
"reviewed_at": 1770097500.456
}
}
}
```
### Audit Status Values
| Status | Description |
|--------|-------------|
| `pending` | Awaiting review by a code reviewer agent |
| `approved` | Approved - requesting agent may proceed with changes |
| `rejected` | Rejected - requesting agent must address feedback and resubmit |
## Integration with read_state
The `read_state` tool now displays a code audit summary:
```
**Code Audits:**
⏳ Pending: 2
✅ Approved: 5
❌ Rejected: 1
🔔 Pending Review:
- audit-a1b2c3d4: Node-Dev-001 → src/utils.py, src/main.py
- audit-i9j0k1l2: Node-Dev-002 → src/config.py
```
## Best Practices
### For Developers
1. **Always submit an audit before file changes** - This ensures code quality and team awareness
2. **Provide clear descriptions** - Help reviewers understand the purpose of changes
3. **Include meaningful proposed_changes** - Show actual code or comprehensive diffs
4. **Check audit status before proceeding** - Use `get_audit_status` to confirm approval
### For Reviewers
1. **Check pending audits regularly** - Use `get_pending_audits` to see work awaiting review
2. **Provide constructive feedback** - When rejecting, explain what needs to change
3. **Review high-priority audits first** - They are sorted by priority
### For Bootstrap Managers
1. **Assign reviewer roles** - Ensure cluster has agents designated for code review
2. **Monitor audit queue** - Use `list_code_audits(status_filter="pending")` to track backlog
3. **Balance workload** - Consider audit review time when assigning tasks
## Example Workflow
```python
# Developer agent submits audit
result = submit_code_audit_request(
requesting_agent="Node-Dev-001",
files=["src/server.py"],
description="Adding new API endpoint for user settings",
proposed_changes="@app.route('/settings')\ndef get_settings(): ...",
priority="high"
)
# audit_id = "audit-abc123"
# Developer waits and periodically checks status
status = get_audit_status("audit-abc123")
# Status: PENDING
# Reviewer agent checks pending audits
pending = get_pending_audits()
# Shows audit-abc123 needs review
# Reviewer approves the audit
approve_code_audit(
audit_id="audit-abc123",
reviewer_agent="Node-Reviewer-001",
feedback="LGTM - clean implementation"
)
# Developer checks status again
status = get_audit_status("audit-abc123")
# Status: APPROVED - may proceed
# Developer now makes the actual file changes
```
## Security Considerations
- **Path validation**: All file paths are validated to be within the project root
- **Self-review prevention**: Agents cannot approve or reject their own audits
- **Audit trail**: All audits are logged with timestamps and agent IDs
- **Required feedback**: Rejections require feedback to ensure constructive review
## Version History
- **v0.6.0** (2026-02-02): Initial implementation of code audit governance
- Added 6 MCP tools for audit workflow
- Integrated with state.json schema
- Added audit display to read_state
