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, 31 insertions, 0 deletions

diff --git a/makima/src/db/models.rs b/makima/src/db/models.rs
index a6b5b05..636d81a 100644
--- a/makima/src/db/models.rs
+++ b/makima/src/db/models.rs
@@ -1808,6 +1808,37 @@ pub struct ChangePhaseRequest {
     /// User feedback for changes (used when not confirming)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub feedback: Option<String>,
+    /// Expected version for optimistic locking. If provided, the phase change
+    /// will only succeed if the current contract version matches.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub expected_version: Option<i32>,
+}
+
+/// Result of a phase change operation, supporting explicit conflict detection.
+#[derive(Debug, Clone)]
+pub enum PhaseChangeResult {
+    /// Phase change succeeded, returning the updated contract
+    Success(Contract),
+    /// Version conflict: the contract was modified concurrently
+    VersionConflict {
+        /// The version the client expected
+        expected: i32,
+        /// The actual current version in the database
+        actual: i32,
+        /// The current phase of the contract
+        current_phase: String,
+    },
+    /// Validation failed (e.g., invalid phase transition)
+    ValidationFailed {
+        /// Human-readable reason for the failure
+        reason: String,
+        /// List of missing requirements for the phase transition
+        missing_requirements: Vec<String>,
+    },
+    /// The caller is not authorized to change this contract's phase
+    Unauthorized,
+    /// The contract was not found
+    NotFound,
 }
 
 /// Response for phase transition when phase_guard is enabled