# Contract Management System Specification
**Version**: 1.0.0
**Status**: Draft
**Author**: AI Assistant
**Date**: 2025-01-31
## Executive Summary
This specification addresses critical issues in the current contract management system:
1. **Manual Completion Required** - Contracts stay 'active' indefinitely
2. **No Phase Readiness Validation** - No automatic checking before phase advancement
3. **Supervisor State Restoration Broken** - Context lost after daemon crash
4. **Version Conflicts Silent** - Phase changes can fail silently
5. **No Deliverable Validation** - Can mark non-existent deliverables as complete
6. **Phase Guard Supervisor Bypass** - Supervisors can bypass phase_guard setting
---
## 1. Contract Lifecycle State Machine
### 1.1 Current State (ContractStatus)
The current implementation uses three states:
- `active` - Contract is being worked on
- `completed` - Contract finished successfully
- `archived` - Contract archived (soft delete)
### 1.2 Proposed State Machine
```
┌─────────────────────────────────────────────┐
│ │
▼ │
┌────────┐ ┌─────────┐ ┌──────────────────┐ ┌────────────┴───┐
│ created ├───►│ active ├───►│ waiting_for_input├───►│ completing │
└────────┘ └────┬────┘ └────────┬─────────┘ └───────┬────────┘
│ │ │
│ │ ▼
│ │ ┌───────────────┐
│ │ │ completed │
│ │ └───────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌───────────────┐
│ paused │ │ blocked │ │ archived │
└────┬────┘ └────┬─────┘ └───────────────┘
│ │ ▲
└────────────────┴───────────────────────┤
│
┌────────┐ │
│ failed ├───────────────────────────────┘
└────────┘
```
### 1.3 State Definitions
```rust
/// Contract lifecycle states
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ContractStatus {
/// Contract created but not yet started
Created,
/// Contract is actively being worked on
Active,
/// Waiting for user input (phase confirmation, question, etc.)
WaitingForInput,
/// Contract is paused by user request
Paused,
/// Contract is blocked on external dependency
Blocked,
/// All phases complete, running final validation
Completing,
/// Contract completed successfully
Completed,
/// Contract failed with errors
Failed,
/// Contract archived (soft delete)
Archived,
}
```
### 1.4 State Transitions
| From State | To State | Guard Conditions | Trigger |
|------------|----------|------------------|---------|
| Created | Active | Has supervisor task | Supervisor starts |
| Active | WaitingForInput | Pending question exists | Supervisor asks question |
| Active | Paused | - | User requests pause |
| Active | Blocked | Has external blocker | Blocker detected |
| Active | Completing | Final phase, all deliverables met | Auto-completion check |
| WaitingForInput | Active | Question answered | User responds |
| WaitingForInput | Paused | - | Timeout or user pause |
| Paused | Active | - | User resumes |
| Blocked | Active | Blocker resolved | Blocker cleared |
| Completing | Completed | All cleanup done | Completion confirmed |
| Completing | Active | Completion rejected | User rejects |
| Any | Failed | Unrecoverable error | Error detected |
| Completed | Archived | - | User archives |
| Failed | Archived | - | User archives |
### 1.5 Timeout and Stale Detection
```rust
/// Configuration for contract timeout and stale detection
pub struct ContractTimeoutConfig {
/// Time after last supervisor activity before contract is considered stale
pub stale_threshold: Duration, // Default: 30 minutes
/// Time to wait for user input before timing out
pub input_timeout: Duration, // Default: 24 hours
/// Time before completing contracts are auto-completed
pub completion_grace_period: Duration, // Default: 5 minutes
/// Time before archived contracts are deleted
pub archive_retention: Duration, // Default: 30 days
}
impl Default for ContractTimeoutConfig {
fn default() -> Self {
Self {
stale_threshold: Duration::from_secs(30 * 60),
input_timeout: Duration::from_secs(24 * 60 * 60),
completion_grace_period: Duration::from_secs(5 * 60),
archive_retention: Duration::from_secs(30 * 24 * 60 * 60),
}
}
}
```
### 1.6 Database Schema Changes
```sql
-- Add new status column options and tracking fields
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
status_changed_at TIMESTAMPTZ DEFAULT NOW();
-- Track last activity for stale detection
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
last_activity_at TIMESTAMPTZ DEFAULT NOW();
-- Track pending input
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
waiting_for TEXT; -- 'question', 'phase_confirmation', 'completion_confirmation'
-- Track blockers
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
blocked_reason TEXT;
-- Track failure reason
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
failure_reason TEXT;
-- Index for status queries
CREATE INDEX idx_contracts_status ON contracts(status);
CREATE INDEX idx_contracts_last_activity ON contracts(last_activity_at);
```
### 1.7 API Changes
```rust
/// Request to change contract state
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ChangeStatusRequest {
pub target_status: ContractStatus,
/// Required for some transitions
pub reason: Option<String>,
/// For blocking states, what is blocking
pub blocker: Option<String>,
}
/// Response for status change
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ChangeStatusResponse {
pub success: bool,
pub previous_status: ContractStatus,
pub new_status: ContractStatus,
/// If transition failed, why
pub rejection_reason: Option<String>,
}
```
---
## 2. Automatic Completion Detection
### 2.1 Current Problem
Contracts currently require manual `supervisor_complete()` calls. Supervisors may exit without completing contracts, leaving them active indefinitely.
### 2.2 Proposed Solution: Completion Gates
#### 2.2.1 Phase Completion Gates
```rust
/// Gate that must be satisfied before advancing to next phase
pub struct PhaseCompletionGate {
/// Required deliverables for this phase
pub required_deliverables: Vec<String>,
/// Required tasks to be completed
pub required_tasks: TaskRequirement,
/// Optional custom validation function
pub custom_validator: Option<Box<dyn Fn(&Contract) -> bool>>,
/// Whether to auto-advance when gate is satisfied
pub auto_advance: bool,
}
/// Task completion requirements
pub enum TaskRequirement {
/// No task requirements
None,
/// All spawned tasks must complete
AllComplete,
/// At least N tasks must complete
MinComplete(usize),
/// Specific named tasks must complete
NamedTasks(Vec<String>),
}
```
#### 2.2.2 Contract Completion Detection
```rust
/// Contract completion detector
pub struct CompletionDetector {
/// Phase-specific gates
phase_gates: HashMap<String, PhaseCompletionGate>,
}
impl CompletionDetector {
/// Check if current phase is ready to advance
pub fn check_phase_readiness(
&self,
contract: &Contract,
tasks: &[TaskSummary],
) -> PhaseReadinessResult {
let gate = match self.phase_gates.get(&contract.phase) {
Some(g) => g,
None => return PhaseReadinessResult::NoGate,
};
let mut missing = Vec::new();
// Check deliverables
let completed = contract.get_completed_deliverables(&contract.phase);
for req in &gate.required_deliverables {
if !completed.contains(req) {
missing.push(format!("Deliverable: {}", req));
}
}
// Check tasks
match &gate.required_tasks {
TaskRequirement::None => {},
TaskRequirement::AllComplete => {
let incomplete = tasks.iter()
.filter(|t| !t.is_supervisor && t.status != "done")
.count();
if incomplete > 0 {
missing.push(format!("{} tasks incomplete", incomplete));
}
},
TaskRequirement::MinComplete(n) => {
let complete = tasks.iter()
.filter(|t| !t.is_supervisor && t.status == "done")
.count();
if complete < *n {
missing.push(format!("Need {} tasks complete, have {}", n, complete));
}
},
TaskRequirement::NamedTasks(names) => {
for name in names {
let found = tasks.iter()
.find(|t| &t.name == name && t.status == "done");
if found.is_none() {
missing.push(format!("Task '{}' not complete", name));
}
}
}
}
if missing.is_empty() {
PhaseReadinessResult::Ready
} else {
PhaseReadinessResult::NotReady { missing }
}
}
/// Check if contract should auto-complete
pub fn check_contract_completion(&self, contract: &Contract) -> bool {
// Must be in terminal phase
if contract.phase != contract.terminal_phase_id() {
return false;
}
// Terminal phase gate must be satisfied
matches!(
self.check_phase_readiness(contract, &[]),
PhaseReadinessResult::Ready
)
}
}
/// Result of phase readiness check
pub enum PhaseReadinessResult {
/// Phase is ready to advance
Ready,
/// Phase is not ready, with list of missing items
NotReady { missing: Vec<String> },
/// No gate defined for this phase
NoGate,
}
```
#### 2.2.3 Auto-Completion Flow
```
┌─────────────────────────────────────────────────────────────────────┐
│ AUTO-COMPLETION FLOW │
└─────────────────────────────────────────────────────────────────────┘
1. Task completes (status = "done")
│
▼
2. Check if any phase gate is now satisfied
│
├─ NO ──► Return, wait for more tasks
│
▼ YES
3. Is auto_advance enabled for phase?
│
├─ NO ──► Notify user, wait for manual advance
│
▼ YES
4. Is phase_guard enabled?
│
├─ YES ─► Set status = WaitingForInput, ask for confirmation
│
▼ NO
5. Auto-advance to next phase
│
▼
6. Is this the terminal phase?
│
├─ NO ──► Continue working
│
▼ YES
7. All terminal deliverables complete?
│
├─ NO ──► Continue working
│
▼ YES
8. Set status = Completing
│
▼
9. Cleanup worktrees, stop supervisor
│
▼
10. Set status = Completed
```
### 2.3 Database Schema Changes
```sql
-- Track auto-completion state
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
auto_complete_enabled BOOLEAN DEFAULT TRUE;
-- Track when completion was detected
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS
completion_detected_at TIMESTAMPTZ;
```
### 2.4 API Endpoints
```rust
/// Check phase readiness
/// GET /api/v1/contracts/{id}/phase-readiness
pub async fn check_phase_readiness(
contract_id: Uuid,
) -> PhaseReadinessResponse;
/// Force completion check
/// POST /api/v1/contracts/{id}/check-completion
pub async fn check_completion(
contract_id: Uuid,
) -> CompletionCheckResponse;
/// Enable/disable auto-completion
/// PUT /api/v1/contracts/{id}/auto-complete
pub async fn set_auto_complete(
contract_id: Uuid,
enabled: bool,
) -> ContractSummary;
```
---
## 3. Supervisor Status Reporting
### 3.1 Current Problem
The `supervisor_states` table exists but:
- State is not reliably persisted during daemon operations
- Restoration after crash doesn't properly resume context
- No clear indication of supervisor's current activity
### 3.2 Proposed Supervisor States
```rust
/// Supervisor execution states
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SupervisorState {
/// Supervisor is starting up
Initializing,
/// Supervisor is idle, no pending work
Idle,
/// Supervisor is actively working (LLM processing)
Working,
/// Supervisor is waiting for user input
WaitingForUser,
/// Supervisor is waiting for child tasks
WaitingForTasks,
/// Supervisor is blocked on external resource
Blocked,
/// Supervisor has completed its work
Completed,
/// Supervisor has failed
Failed,
/// Supervisor was interrupted
Interrupted,
}
```
### 3.3 Heartbeat Mechanism
```rust
/// Heartbeat message from supervisor to server
#[derive(Debug, Serialize, Deserialize)]
pub struct SupervisorHeartbeat {
pub task_id: Uuid,
pub contract_id: Uuid,
pub state: SupervisorState,
pub phase: String,
/// What the supervisor is currently doing
pub current_activity: String,
/// Progress percentage (0-100)
pub progress: u8,
/// IDs of tasks supervisor is waiting on
pub pending_task_ids: Vec<Uuid>,
/// Timestamp
pub timestamp: DateTime<Utc>,
}
/// Heartbeat configuration
pub struct HeartbeatConfig {
/// How often to send heartbeats
pub interval: Duration, // Default: 30 seconds
/// How long before a supervisor is considered dead
pub timeout: Duration, // Default: 2 minutes
}
```
### 3.4 State Persistence
```rust
/// Enhanced supervisor state for persistence
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SupervisorPersistentState {
/// Current supervisor state
pub state: SupervisorState,
/// Current contract phase
pub phase: String,
/// Conversation history for resumption
pub conversation_history: Vec<ConversationMessage>,
/// Currently pending questions
pub pending_questions: Vec<PendingQuestion>,
/// Tasks spawned by this supervisor
pub spawned_task_ids: Vec<Uuid>,
/// Tasks we're waiting on
pub waiting_on_task_ids: Vec<Uuid>,
/// Last checkpoint created
pub last_checkpoint: Option<CheckpointInfo>,
/// Current activity description
pub current_activity: String,
/// Error if in failed state
pub error: Option<String>,
/// Timestamps
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
}
```
### 3.5 Database Schema Changes
```sql
-- Enhance supervisor_states table
ALTER TABLE supervisor_states ADD COLUMN IF NOT EXISTS
state VARCHAR(50) NOT NULL DEFAULT 'initializing';
ALTER TABLE supervisor_states ADD COLUMN IF NOT EXISTS
current_activity TEXT;
ALTER TABLE supervisor_states ADD COLUMN IF NOT EXISTS
progress INTEGER DEFAULT 0;
ALTER TABLE supervisor_states ADD COLUMN IF NOT EXISTS
error_message TEXT;
ALTER TABLE supervisor_states ADD COLUMN IF NOT EXISTS
spawned_task_ids UUID[] DEFAULT ARRAY[]::UUID[];
-- Create heartbeat tracking table
CREATE TABLE IF NOT EXISTS supervisor_heartbeats (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
supervisor_task_id UUID NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
contract_id UUID NOT NULL REFERENCES contracts(id) ON DELETE CASCADE,
state VARCHAR(50) NOT NULL,
phase VARCHAR(50) NOT NULL,
current_activity TEXT,
progress INTEGER DEFAULT 0,
pending_task_ids UUID[] DEFAULT ARRAY[]::UUID[],
timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-- Keep only recent heartbeats
CONSTRAINT heartbeat_ttl CHECK (timestamp > NOW() - INTERVAL '24 hours')
);
CREATE INDEX idx_heartbeats_supervisor ON supervisor_heartbeats(supervisor_task_id);
CREATE INDEX idx_heartbeats_timestamp ON supervisor_heartbeats(timestamp);
```
### 3.6 Restoration Protocol
```
┌─────────────────────────────────────────────────────────────────────┐
│ SUPERVISOR RESTORATION PROTOCOL │
└─────────────────────────────────────────────────────────────────────┘
1. Daemon restarts or task is assigned to new daemon
│
▼
2. Load supervisor state from supervisor_states table
│
├─ NOT FOUND ──► Start fresh, log warning
│
▼ FOUND
3. Validate state consistency
│
├─ INVALID ──► Start from last checkpoint
│
▼ VALID
4. Restore conversation history
│
▼
5. Check for pending questions
│
├─ HAS PENDING ──► Re-deliver questions to user
│
▼ NO PENDING
6. Check for waiting tasks
│
├─ HAS WAITING ──► Resume waiting state
│
▼ NO WAITING
7. Send restoration context to Claude
│
▼
8. Resume execution from last state
```
### 3.7 API Endpoints
```rust
/// Get supervisor status
/// GET /api/v1/contracts/{id}/supervisor/status
pub async fn get_supervisor_status(
contract_id: Uuid,
) -> SupervisorStatusResponse;
/// Get supervisor heartbeat history
/// GET /api/v1/contracts/{id}/supervisor/heartbeats
pub async fn get_heartbeats(
contract_id: Uuid,
limit: Option<i32>,
) -> HeartbeatListResponse;
/// Force supervisor state sync
/// POST /api/v1/contracts/{id}/supervisor/sync
pub async fn sync_supervisor_state(
contract_id: Uuid,
) -> SyncResponse;
```
---
## 4. Contract Monitoring Dashboard
### 4.1 Real-Time Status Updates
#### 4.1.1 WebSocket Events
```rust
/// Contract monitoring events
#[derive(Debug, Serialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum ContractMonitorEvent {
/// Contract status changed
StatusChanged {
contract_id: Uuid,
old_status: ContractStatus,
new_status: ContractStatus,
reason: Option<String>,
},
/// Phase changed
PhaseChanged {
contract_id: Uuid,
old_phase: String,
new_phase: String,
},
/// Supervisor state changed
SupervisorStateChanged {
contract_id: Uuid,
supervisor_task_id: Uuid,
old_state: SupervisorState,
new_state: SupervisorState,
},
/// Supervisor heartbeat received
Heartbeat {
contract_id: Uuid,
state: SupervisorState,
activity: String,
progress: u8,
},
/// Contract became stale
StaleDetected {
contract_id: Uuid,
last_activity: DateTime<Utc>,
stale_duration: Duration,
},
/// Task completed
TaskCompleted {
contract_id: Uuid,
task_id: Uuid,
task_name: String,
success: bool,
},
/// Deliverable marked complete
DeliverableCompleted {
contract_id: Uuid,
phase: String,
deliverable_id: String,
},
/// Question asked (needs user attention)
QuestionAsked {
contract_id: Uuid,
question_id: Uuid,
question: String,
question_type: String,
},
}
```
#### 4.1.2 Subscription API
```rust
/// Subscribe to contract monitoring events
/// WS /api/v1/contracts/monitor
pub async fn monitor_contracts(
ws: WebSocket,
filter: ContractMonitorFilter,
) -> Result<(), Error>;
#[derive(Debug, Deserialize)]
pub struct ContractMonitorFilter {
/// Filter by specific contract IDs
pub contract_ids: Option<Vec<Uuid>>,
/// Filter by status
pub statuses: Option<Vec<ContractStatus>>,
/// Include stale detection events
pub include_stale: bool,
/// Include heartbeat events
pub include_heartbeats: bool,
}
```
### 4.2 Stale Contract Detection
```rust
/// Stale contract detector service
pub struct StaleContractDetector {
pool: PgPool,
config: ContractTimeoutConfig,
}
impl StaleContractDetector {
/// Run stale detection loop
pub async fn run(&self, event_tx: Sender<ContractMonitorEvent>) {
let mut interval = tokio::time::interval(Duration::from_secs(60));
loop {
interval.tick().await;
let stale = self.detect_stale_contracts().await;
for (contract_id, last_activity) in stale {
let _ = event_tx.send(ContractMonitorEvent::StaleDetected {
contract_id,
last_activity,
stale_duration: Utc::now() - last_activity,
}).await;
}
}
}
/// Detect stale contracts
async fn detect_stale_contracts(&self) -> Vec<(Uuid, DateTime<Utc>)> {
let threshold = Utc::now() - self.config.stale_threshold;
sqlx::query_as::<_, (Uuid, DateTime<Utc>)>(
r#"
SELECT id, last_activity_at
FROM contracts
WHERE status = 'active'
AND last_activity_at < $1
"#
)
.bind(threshold)
.fetch_all(&self.pool)
.await
.unwrap_or_default()
}
}
```
### 4.3 Batch Operations
```rust
/// Batch operation types
#[derive(Debug, Deserialize)]
#[serde(tag = "operation", rename_all = "snake_case")]
pub enum BatchOperation {
/// Archive completed contracts older than threshold
ArchiveOld {
older_than: Duration,
status_filter: Vec<ContractStatus>,
},
/// Pause all active contracts
PauseAll {
reason: String,
},
/// Resume all paused contracts
ResumeAll,
/// Delete archived contracts older than threshold
CleanupArchived {
older_than: Duration,
},
/// Restart stale supervisors
RestartStale {
stale_threshold: Duration,
},
}
/// Batch operation result
#[derive(Debug, Serialize)]
pub struct BatchOperationResult {
pub operation: String,
pub affected_count: usize,
pub affected_ids: Vec<Uuid>,
pub errors: Vec<BatchOperationError>,
}
#[derive(Debug, Serialize)]
pub struct BatchOperationError {
pub contract_id: Uuid,
pub error: String,
}
```
### 4.4 Dashboard API
```rust
/// Get dashboard summary
/// GET /api/v1/contracts/dashboard
pub async fn get_dashboard() -> DashboardResponse;
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct DashboardResponse {
/// Count by status
pub status_counts: HashMap<ContractStatus, usize>,
/// Count by phase (for active contracts)
pub phase_counts: HashMap<String, usize>,
/// Stale contracts
pub stale_contracts: Vec<StaleContractInfo>,
/// Contracts waiting for input
pub waiting_for_input: Vec<WaitingContractInfo>,
/// Recent activity
pub recent_events: Vec<ContractMonitorEvent>,
/// Resource usage
pub resource_usage: ResourceUsage,
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct StaleContractInfo {
pub id: Uuid,
pub name: String,
pub phase: String,
pub last_activity: DateTime<Utc>,
pub stale_duration_secs: i64,
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct WaitingContractInfo {
pub id: Uuid,
pub name: String,
pub waiting_for: String, // 'question', 'phase_confirmation', etc.
pub waiting_since: DateTime<Utc>,
pub question: Option<String>,
}
#[derive(Debug, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct ResourceUsage {
pub active_supervisors: usize,
pub running_tasks: usize,
pub pending_tasks: usize,
pub active_daemons: usize,
pub total_worktrees: usize,
}
```
---
## 5. Improved CLI Commands
### 5.1 Contract Listing with Filters
```bash
# List all contracts
makima contracts list
# List with status filter
makima contracts list --status active
makima contracts list --status completed,failed
# List stale contracts
makima contracts list --stale
makima contracts list --stale --threshold 30m
# List contracts waiting for input
makima contracts list --waiting
# List by phase
makima contracts list --phase execute
# Combine filters
makima contracts list --status active --phase plan --stale
# Output formats
makima contracts list --format json
makima contracts list --format table
makima contracts list --format compact
```
#### Implementation
```rust
#[derive(Debug, Args)]
pub struct ListContractsArgs {
/// Filter by status (comma-separated)
#[arg(long)]
pub status: Option<String>,
/// Show only stale contracts
#[arg(long)]
pub stale: bool,
/// Stale threshold (e.g., "30m", "1h")
#[arg(long, default_value = "30m")]
pub threshold: String,
/// Show contracts waiting for input
#[arg(long)]
pub waiting: bool,
/// Filter by phase
#[arg(long)]
pub phase: Option<String>,
/// Output format
#[arg(long, default_value = "table")]
pub format: OutputFormat,
/// Limit results
#[arg(long, short = 'n')]
pub limit: Option<usize>,
}
```
### 5.2 Cleanup Command
```bash
# Archive completed contracts older than 7 days
makima contracts cleanup --archive --older-than 7d
# Delete archived contracts older than 30 days
makima contracts cleanup --delete-archived --older-than 30d
# Dry run (show what would be affected)
makima contracts cleanup --archive --older-than 7d --dry-run
# Force cleanup without confirmation
makima contracts cleanup --archive --older-than 7d --force
# Cleanup stale worktrees
makima contracts cleanup --worktrees
# Full cleanup: archive old, delete archived, clean worktrees
makima contracts cleanup --all --older-than 7d
```
#### Implementation
```rust
#[derive(Debug, Args)]
pub struct CleanupContractsArgs {
/// Archive completed/failed contracts
#[arg(long)]
pub archive: bool,
/// Delete archived contracts
#[arg(long)]
pub delete_archived: bool,
/// Clean up orphaned worktrees
#[arg(long)]
pub worktrees: bool,
/// Run all cleanup operations
#[arg(long)]
pub all: bool,
/// Threshold for cleanup (e.g., "7d", "30d")
#[arg(long, default_value = "7d")]
pub older_than: String,
/// Dry run - show what would be affected
#[arg(long)]
pub dry_run: bool,
/// Skip confirmation prompts
#[arg(long)]
pub force: bool,
}
```
### 5.3 Monitor Command
```bash
# Real-time monitoring dashboard
makima contracts monitor
# Monitor specific contracts
makima contracts monitor <contract-id> <contract-id>
# Monitor with filters
makima contracts monitor --status active
makima contracts monitor --stale
# Quiet mode - only show important events
makima contracts monitor --quiet
# JSON output for scripting
makima contracts monitor --format json
```
#### Implementation
```rust
#[derive(Debug, Args)]
pub struct MonitorContractsArgs {
/// Contract IDs to monitor (empty = all)
pub contract_ids: Vec<Uuid>,
/// Filter by status
#[arg(long)]
pub status: Option<String>,
/// Only show stale contracts
#[arg(long)]
pub stale: bool,
/// Quiet mode - only important events
#[arg(long, short)]
pub quiet: bool,
/// Output format
#[arg(long, default_value = "tui")]
pub format: MonitorFormat,
}
#[derive(Debug, Clone, ValueEnum)]
pub enum MonitorFormat {
/// Terminal UI dashboard
Tui,
/// Plain text output
Text,
/// JSON stream
Json,
}
```
### 5.4 Additional Commands
```bash
# Resume a paused contract
makima contracts resume <contract-id>
# Pause an active contract
makima contracts pause <contract-id> --reason "Waiting for external review"
# Force advance phase
makima contracts advance <contract-id> --phase execute --force
# Restart stale supervisor
makima contracts restart-supervisor <contract-id>
# Show contract details
makima contracts show <contract-id> --verbose
# Check contract health
makima contracts health <contract-id>
# Export contract history
makima contracts export <contract-id> --format json --output contract.json
```
---
## 6. Bug Fixes
### 6.1 Version Conflicts (Silent Failures)
**Problem**: Phase changes can fail silently when version conflicts occur.
**Solution**: Implement explicit version checking and conflict reporting.
```rust
/// Result type for phase changes with explicit conflict handling
pub enum PhaseChangeResult {
Success(Contract),
VersionConflict {
expected: i32,
actual: i32,
current_phase: String,
},
ValidationFailed {
reason: String,
missing_requirements: Vec<String>,
},
Unauthorized,
NotFound,
}
/// Enhanced phase change handler
pub async fn change_phase_with_validation(
pool: &PgPool,
contract_id: Uuid,
owner_id: Uuid,
new_phase: &str,
expected_version: Option<i32>,
) -> Result<PhaseChangeResult, Error> {
// Start transaction
let mut tx = pool.begin().await?;
// Get current contract with lock
let contract = sqlx::query_as::<_, Contract>(
"SELECT * FROM contracts WHERE id = $1 AND owner_id = $2 FOR UPDATE"
)
.bind(contract_id)
.bind(owner_id)
.fetch_optional(&mut *tx)
.await?;
let contract = match contract {
Some(c) => c,
None => return Ok(PhaseChangeResult::NotFound),
};
// Check version if provided
if let Some(expected) = expected_version {
if contract.version != expected {
return Ok(PhaseChangeResult::VersionConflict {
expected,
actual: contract.version,
current_phase: contract.phase.clone(),
});
}
}
// Validate phase transition
let validation = validate_phase_transition(&contract, new_phase);
if !validation.valid {
return Ok(PhaseChangeResult::ValidationFailed {
reason: validation.reason,
missing_requirements: validation.missing,
});
}
// Update phase
let updated = sqlx::query_as::<_, Contract>(
r#"
UPDATE contracts
SET phase = $1, version = version + 1, updated_at = NOW()
WHERE id = $2
RETURNING *
"#
)
.bind(new_phase)
.bind(contract_id)
.fetch_one(&mut *tx)
.await?;
tx.commit().await?;
Ok(PhaseChangeResult::Success(updated))
}
```
### 6.2 Deliverable Validation
**Problem**: Can mark non-existent deliverables as complete.
**Solution**: Validate deliverable IDs before marking complete.
```rust
/// Validate deliverable exists for contract type and phase
pub fn validate_deliverable(
contract_type: &str,
phase: &str,
deliverable_id: &str,
phase_config: Option<&PhaseConfig>,
) -> Result<(), DeliverableValidationError> {
let deliverables = if let Some(config) = phase_config {
get_phase_deliverables_from_config(phase, config)
} else {
get_phase_deliverables_for_type(phase, contract_type)
};
let valid_ids: Vec<&str> = deliverables
.deliverables
.iter()
.map(|d| d.id.as_str())
.collect();
if !valid_ids.contains(&deliverable_id) {
return Err(DeliverableValidationError::InvalidDeliverable {
deliverable_id: deliverable_id.to_string(),
phase: phase.to_string(),
valid_ids: valid_ids.into_iter().map(String::from).collect(),
});
}
Ok(())
}
#[derive(Debug, thiserror::Error)]
pub enum DeliverableValidationError {
#[error("Invalid deliverable '{deliverable_id}' for {phase} phase. Valid IDs: {valid_ids:?}")]
InvalidDeliverable {
deliverable_id: String,
phase: String,
valid_ids: Vec<String>,
},
}
```
### 6.3 Phase Guard Bypass
**Problem**: Supervisors can bypass phase_guard setting.
**Solution**: Enforce phase_guard at the API level, not just in supervisor logic.
```rust
/// Enhanced phase change with phase_guard enforcement
pub async fn change_phase_enforced(
pool: &PgPool,
contract_id: Uuid,
owner_id: Uuid,
request: ChangePhaseRequest,
is_supervisor: bool,
) -> Result<PhaseChangeResponse, Error> {
let contract = get_contract_for_owner(pool, contract_id, owner_id).await?
.ok_or_else(|| Error::NotFound)?;
// Phase guard is enforced for EVERYONE, including supervisors
if contract.phase_guard && !request.confirmed.unwrap_or(false) {
// Must return phase review info, regardless of caller
return Ok(PhaseChangeResponse::RequiresConfirmation {
current_phase: contract.phase,
next_phase: request.phase,
deliverables: get_phase_deliverables(&contract.phase),
message: "Phase guard is enabled. User confirmation required.".to_string(),
});
}
// Proceed with phase change
// ...
}
```
---
## 7. Migration Plan
### 7.1 Phase 1: Database Schema (Week 1)
1. Add new columns to `contracts` table
2. Add new columns to `supervisor_states` table
3. Create `supervisor_heartbeats` table
4. Create indexes
5. Backfill `last_activity_at` from existing data
```sql
-- Migration 001: Contract status enhancements
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS status_changed_at TIMESTAMPTZ DEFAULT NOW();
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS last_activity_at TIMESTAMPTZ DEFAULT NOW();
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS waiting_for TEXT;
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS blocked_reason TEXT;
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS failure_reason TEXT;
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS auto_complete_enabled BOOLEAN DEFAULT TRUE;
ALTER TABLE contracts ADD COLUMN IF NOT EXISTS completion_detected_at TIMESTAMPTZ;
CREATE INDEX IF NOT EXISTS idx_contracts_status ON contracts(status);
CREATE INDEX IF NOT EXISTS idx_contracts_last_activity ON contracts(last_activity_at);
-- Backfill last_activity_at from updated_at
UPDATE contracts SET last_activity_at = updated_at WHERE last_activity_at IS NULL;
```
### 7.2 Phase 2: Core Logic (Week 2)
1. Implement `ContractStatus` enum with new states
2. Implement state transition validation
3. Implement `CompletionDetector`
4. Update phase change handlers with validation
5. Implement deliverable validation
### 7.3 Phase 3: Supervisor Enhancements (Week 3)
1. Implement `SupervisorState` enum
2. Implement heartbeat mechanism
3. Implement state persistence
4. Implement restoration protocol
5. Update supervisor API endpoints
### 7.4 Phase 4: Monitoring (Week 4)
1. Implement WebSocket monitoring events
2. Implement stale detection service
3. Implement batch operations
4. Implement dashboard API
### 7.5 Phase 5: CLI (Week 5)
1. Implement `contracts list` with filters
2. Implement `contracts cleanup`
3. Implement `contracts monitor`
4. Implement additional helper commands
### 7.6 Phase 6: Testing & Rollout (Week 6)
1. Unit tests for all new components
2. Integration tests for state machines
3. Load testing for monitoring
4. Staged rollout with feature flags
5. Documentation updates
---
## 8. Appendix
### 8.1 Configuration Options
```toml
[contracts]
# Timeout configuration
stale_threshold_minutes = 30
input_timeout_hours = 24
completion_grace_period_minutes = 5
archive_retention_days = 30
# Auto-completion
auto_complete_enabled = true
auto_advance_phases = true
# Heartbeat
heartbeat_interval_seconds = 30
heartbeat_timeout_seconds = 120
# Monitoring
monitor_ws_buffer_size = 1000
stale_detection_interval_seconds = 60
```
### 8.2 Error Codes
| Code | Description |
|------|-------------|
| `CONTRACT_NOT_FOUND` | Contract does not exist |
| `INVALID_TRANSITION` | State transition not allowed |
| `VERSION_CONFLICT` | Optimistic locking conflict |
| `PHASE_GUARD_REQUIRED` | Phase guard confirmation needed |
| `INVALID_DELIVERABLE` | Deliverable ID not valid for phase |
| `SUPERVISOR_NOT_FOUND` | No supervisor for contract |
| `SUPERVISOR_DEAD` | Supervisor heartbeat timeout |
| `VALIDATION_FAILED` | Phase requirements not met |
### 8.3 Metrics
The following metrics should be tracked:
- `contracts_by_status` (gauge) - Count of contracts by status
- `contracts_stale_count` (gauge) - Number of stale contracts
- `phase_transitions_total` (counter) - Phase changes by from/to
- `completion_detections_total` (counter) - Auto-completions detected
- `supervisor_heartbeats_total` (counter) - Heartbeats received
- `supervisor_restarts_total` (counter) - Supervisor restarts
- `batch_operations_total` (counter) - Batch operations by type
