feat: Add contract management system improvements (Phase 1)makima/contract-management-improvements

- Add docs/contract-management-spec.md with full system design
- Add docs/plans/implementation-plan.md with 5-phase rollout plan
- Add validate_deliverable() function and use in mark_deliverable_complete
- Add PhaseChangeResult enum and change_contract_phase_with_version() with FOR UPDATE locking
- Enforce phase_guard at API level for all callers

This addresses critical issues in contract management:
- Deliverable validation to prevent marking non-existent deliverables complete
- Version conflict detection for phase changes with row locking
- Phase guard enforcement at API level (applies to all callers including supervisors)
- Comprehensive specification and implementation plan for future phases

1 files changed, 19 insertions, 2 deletions

diff --git a/makima/src/server/handlers/contract_chat.rs b/makima/src/server/handlers/contract_chat.rs
index b5255f5..b025485 100644
--- a/makima/src/server/handlers/contract_chat.rs
+++ b/makima/src/server/handlers/contract_chat.rs
@@ -1812,7 +1812,8 @@ async fn handle_contract_request(
                     };
                 }
 
-                // If not confirmed, return pending confirmation with phase deliverables
+                // If not confirmed, return requires_confirmation with phase deliverables
+                // This applies to ALL callers (including supervisors) - phase_guard enforcement at API level
                 if !confirmed {
                     // Get files created in this phase
                     let phase_files = match repository::list_files_in_contract(pool, contract_id, owner_id).await {
@@ -1842,6 +1843,20 @@ async fn handle_contract_request(
                         Err(_) => Vec::new(),
                     };
 
+                    // Get phase deliverables with completion status
+                    let phase_deliverables = crate::llm::get_phase_deliverables_for_type(current_phase, &contract.contract_type);
+                    let completed_deliverables = contract.get_completed_deliverables(current_phase);
+
+                    let deliverables: Vec<serde_json::Value> = phase_deliverables
+                        .deliverables
+                        .iter()
+                        .map(|d| json!({
+                            "id": d.id,
+                            "name": d.name,
+                            "completed": completed_deliverables.contains(&d.id)
+                        }))
+                        .collect();
+
                     // Build deliverables summary
                     let deliverables_summary = format!(
                         "Phase '{}' deliverables: {} files created, {} tasks completed.",
@@ -1859,14 +1874,16 @@ async fn handle_contract_request(
                             new_phase
                         ),
                         data: Some(json!({
-                            "status": "pending_confirmation",
+                            "status": "requires_confirmation",
                             "transitionId": transition_id,
                             "currentPhase": current_phase,
                             "nextPhase": new_phase,
                             "deliverablesSummary": deliverables_summary,
+                            "deliverables": deliverables,
                             "phaseFiles": phase_files,
                             "phaseTasks": phase_tasks,
                             "requiresConfirmation": true,
+                            "message": "Phase guard is enabled. User confirmation required.",
                             "instructions": "To proceed: call advance_phase with confirmed=true. To request changes: call advance_phase with feedback='your feedback here'"
                         })),
                     };