diff options
Diffstat (limited to 'docs/contract-management-spec.md')
| -rw-r--r-- | docs/contract-management-spec.md | 1337 |
1 files changed, 1337 insertions, 0 deletions
diff --git a/docs/contract-management-spec.md b/docs/contract-management-spec.md new file mode 100644 index 0000000..c7f948a --- /dev/null +++ b/docs/contract-management-spec.md @@ -0,0 +1,1337 @@ +# 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 |