Contract system

1 files changed, 594 insertions, 0 deletions

diff --git a/makima/src/llm/phase_guidance.rs b/makima/src/llm/phase_guidance.rs
new file mode 100644
index 0000000..e2d6cd8
--- /dev/null
+++ b/makima/src/llm/phase_guidance.rs
@@ -0,0 +1,594 @@
+//! Phase guidance and deliverables tracking for contract management.
+//!
+//! This module provides structured guidance for each contract phase, tracking
+//! expected deliverables and completion criteria.
+
+use serde::{Deserialize, Serialize};
+use utoipa::ToSchema;
+use uuid::Uuid;
+
+/// Priority level for recommended deliverables
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, ToSchema)]
+#[serde(rename_all = "lowercase")]
+pub enum FilePriority {
+    /// Must exist before advancing phase
+    Required,
+    /// Strongly suggested for phase completion
+    Recommended,
+    /// Nice to have, not blocking
+    Optional,
+}
+
+/// A recommended file for a phase
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RecommendedFile {
+    /// Template ID to create from
+    pub template_id: String,
+    /// Suggested file name
+    pub name_suggestion: String,
+    /// Priority level
+    pub priority: FilePriority,
+    /// Brief description of purpose
+    pub description: String,
+}
+
+/// Expected deliverables for a phase
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PhaseDeliverables {
+    /// Phase name
+    pub phase: String,
+    /// Recommended files to create
+    pub recommended_files: Vec<RecommendedFile>,
+    /// Whether a repository is required for this phase
+    pub requires_repository: bool,
+    /// Whether tasks should exist in this phase
+    pub requires_tasks: bool,
+    /// Guidance text for this phase
+    pub guidance: String,
+}
+
+/// Status of a deliverable item
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct DeliverableStatus {
+    /// Template ID
+    pub template_id: String,
+    /// Expected name
+    pub name: String,
+    /// Priority
+    pub priority: FilePriority,
+    /// Whether it has been created
+    pub completed: bool,
+    /// File ID if created
+    pub file_id: Option<Uuid>,
+    /// Actual file name if created
+    pub actual_name: Option<String>,
+}
+
+/// Checklist for phase completion
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct PhaseChecklist {
+    /// Current phase
+    pub phase: String,
+    /// File deliverables status
+    pub file_deliverables: Vec<DeliverableStatus>,
+    /// Whether repository is configured
+    pub has_repository: bool,
+    /// Whether repository was required
+    pub repository_required: bool,
+    /// Task statistics (for execute phase)
+    pub task_stats: Option<TaskStats>,
+    /// Overall completion percentage (0-100)
+    pub completion_percentage: u8,
+    /// Summary message
+    pub summary: String,
+    /// Suggestions for next actions
+    pub suggestions: Vec<String>,
+}
+
+/// Task statistics for execute phase
+#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
+pub struct TaskStats {
+    pub total: usize,
+    pub pending: usize,
+    pub running: usize,
+    pub done: usize,
+    pub failed: usize,
+}
+
+/// Minimal file info for checklist building
+pub struct FileInfo {
+    pub id: Uuid,
+    pub name: String,
+    pub contract_phase: Option<String>,
+}
+
+/// Minimal task info for checklist building
+pub struct TaskInfo {
+    pub id: Uuid,
+    pub name: String,
+    pub status: String,
+}
+
+/// Get phase deliverables configuration
+pub fn get_phase_deliverables(phase: &str) -> PhaseDeliverables {
+    match phase {
+        "research" => PhaseDeliverables {
+            phase: "research".to_string(),
+            recommended_files: vec![
+                RecommendedFile {
+                    template_id: "research-notes".to_string(),
+                    name_suggestion: "Research Notes".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Document findings and insights during research".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "competitor-analysis".to_string(),
+                    name_suggestion: "Competitor Analysis".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Analyze competitors and market positioning".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "user-research".to_string(),
+                    name_suggestion: "User Research".to_string(),
+                    priority: FilePriority::Optional,
+                    description: "Document user interviews and persona insights".to_string(),
+                },
+            ],
+            requires_repository: false,
+            requires_tasks: false,
+            guidance: "Focus on understanding the problem space, gathering information, and documenting findings. Create at least one research document before moving to Specify phase.".to_string(),
+        },
+        "specify" => PhaseDeliverables {
+            phase: "specify".to_string(),
+            recommended_files: vec![
+                RecommendedFile {
+                    template_id: "requirements".to_string(),
+                    name_suggestion: "Requirements Document".to_string(),
+                    priority: FilePriority::Required,
+                    description: "Define functional and non-functional requirements".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "user-stories".to_string(),
+                    name_suggestion: "User Stories".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Define features from the user's perspective".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "acceptance-criteria".to_string(),
+                    name_suggestion: "Acceptance Criteria".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Define testable conditions for completion".to_string(),
+                },
+            ],
+            requires_repository: false,
+            requires_tasks: false,
+            guidance: "Define what needs to be built with clear requirements and acceptance criteria. Ensure specifications are detailed enough for planning.".to_string(),
+        },
+        "plan" => PhaseDeliverables {
+            phase: "plan".to_string(),
+            recommended_files: vec![
+                RecommendedFile {
+                    template_id: "architecture".to_string(),
+                    name_suggestion: "Architecture Document".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Document system architecture and design decisions".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "task-breakdown".to_string(),
+                    name_suggestion: "Task Breakdown".to_string(),
+                    priority: FilePriority::Required,
+                    description: "Break down work into implementable tasks".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "technical-design".to_string(),
+                    name_suggestion: "Technical Design".to_string(),
+                    priority: FilePriority::Optional,
+                    description: "Detailed technical specification".to_string(),
+                },
+            ],
+            requires_repository: true,
+            requires_tasks: false,
+            guidance: "Design the solution and break down work into tasks. A repository must be configured before moving to Execute phase.".to_string(),
+        },
+        "execute" => PhaseDeliverables {
+            phase: "execute".to_string(),
+            recommended_files: vec![
+                RecommendedFile {
+                    template_id: "dev-notes".to_string(),
+                    name_suggestion: "Development Notes".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Track implementation details and decisions".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "test-plan".to_string(),
+                    name_suggestion: "Test Plan".to_string(),
+                    priority: FilePriority::Optional,
+                    description: "Document testing strategy and test cases".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "implementation-log".to_string(),
+                    name_suggestion: "Implementation Log".to_string(),
+                    priority: FilePriority::Optional,
+                    description: "Chronological log of implementation progress".to_string(),
+                },
+            ],
+            requires_repository: true,
+            requires_tasks: true,
+            guidance: "Execute the planned tasks, implement features, and track progress. Complete all tasks before moving to Review phase.".to_string(),
+        },
+        "review" => PhaseDeliverables {
+            phase: "review".to_string(),
+            recommended_files: vec![
+                RecommendedFile {
+                    template_id: "release-notes".to_string(),
+                    name_suggestion: "Release Notes".to_string(),
+                    priority: FilePriority::Required,
+                    description: "Document changes for release communication".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "review-checklist".to_string(),
+                    name_suggestion: "Review Checklist".to_string(),
+                    priority: FilePriority::Recommended,
+                    description: "Comprehensive checklist for code and feature review".to_string(),
+                },
+                RecommendedFile {
+                    template_id: "retrospective".to_string(),
+                    name_suggestion: "Retrospective".to_string(),
+                    priority: FilePriority::Optional,
+                    description: "Reflect on the project and capture learnings".to_string(),
+                },
+            ],
+            requires_repository: false,
+            requires_tasks: false,
+            guidance: "Review completed work, document the release, and conduct a retrospective. The contract can be completed after review.".to_string(),
+        },
+        _ => PhaseDeliverables {
+            phase: phase.to_string(),
+            recommended_files: vec![],
+            requires_repository: false,
+            requires_tasks: false,
+            guidance: "Unknown phase".to_string(),
+        },
+    }
+}
+
+/// Build a phase checklist comparing expected vs actual deliverables
+pub fn get_phase_checklist(
+    phase: &str,
+    files: &[FileInfo],
+    tasks: &[TaskInfo],
+    has_repository: bool,
+) -> PhaseChecklist {
+    let deliverables = get_phase_deliverables(phase);
+
+    // Match files to expected deliverables
+    let file_deliverables: Vec<DeliverableStatus> = deliverables
+        .recommended_files
+        .iter()
+        .map(|rec| {
+            // Check if a file with matching template ID or similar name exists
+            let matched_file = files.iter().find(|f| {
+                // Match by phase first
+                f.contract_phase.as_deref() == Some(phase) &&
+                // Then by name similarity (case-insensitive contains)
+                (f.name.to_lowercase().contains(&rec.name_suggestion.to_lowercase()) ||
+                 rec.name_suggestion.to_lowercase().contains(&f.name.to_lowercase()) ||
+                 f.name.to_lowercase().contains(&rec.template_id.replace("-", " ")))
+            });
+
+            DeliverableStatus {
+                template_id: rec.template_id.clone(),
+                name: rec.name_suggestion.clone(),
+                priority: rec.priority,
+                completed: matched_file.is_some(),
+                file_id: matched_file.map(|f| f.id),
+                actual_name: matched_file.map(|f| f.name.clone()),
+            }
+        })
+        .collect();
+
+    // Calculate task stats for execute phase
+    let task_stats = if phase == "execute" {
+        let total = tasks.len();
+        let pending = tasks.iter().filter(|t| t.status == "pending").count();
+        let running = tasks.iter().filter(|t| t.status == "running").count();
+        let done = tasks.iter().filter(|t| t.status == "done").count();
+        let failed = tasks.iter().filter(|t| t.status == "failed" || t.status == "error").count();
+
+        Some(TaskStats { total, pending, running, done, failed })
+    } else {
+        None
+    };
+
+    // Calculate completion percentage
+    let mut completed_items = 0;
+    let mut total_items = 0;
+
+    // Count required and recommended files (not optional)
+    for status in &file_deliverables {
+        if status.priority != FilePriority::Optional {
+            total_items += 1;
+            if status.completed {
+                completed_items += 1;
+            }
+        }
+    }
+
+    // Count repository if required
+    if deliverables.requires_repository {
+        total_items += 1;
+        if has_repository {
+            completed_items += 1;
+        }
+    }
+
+    // Count tasks if in execute phase
+    if let Some(ref stats) = task_stats {
+        if stats.total > 0 {
+            total_items += 1;
+            if stats.done == stats.total && stats.total > 0 {
+                completed_items += 1;
+            }
+        }
+    }
+
+    let completion_percentage = if total_items > 0 {
+        ((completed_items as f64 / total_items as f64) * 100.0) as u8
+    } else {
+        100 // No requirements means complete
+    };
+
+    // Generate suggestions
+    let mut suggestions = Vec::new();
+
+    // Suggest missing required files
+    for status in &file_deliverables {
+        if !status.completed {
+            match status.priority {
+                FilePriority::Required => {
+                    suggestions.push(format!("Create {} (required)", status.name));
+                }
+                FilePriority::Recommended => {
+                    suggestions.push(format!("Consider creating {} (recommended)", status.name));
+                }
+                FilePriority::Optional => {
+                    // Don't suggest optional items
+                }
+            }
+        }
+    }
+
+    // Suggest repository if needed
+    if deliverables.requires_repository && !has_repository {
+        suggestions.push("Configure a repository for task execution".to_string());
+    }
+
+    // Suggest task actions for execute phase
+    if let Some(ref stats) = task_stats {
+        if stats.total == 0 {
+            suggestions.push("Create tasks from the Task Breakdown document".to_string());
+        } else if stats.pending > 0 {
+            suggestions.push(format!("Run {} pending task(s)", stats.pending));
+        } else if stats.running > 0 {
+            suggestions.push(format!("Wait for {} running task(s) to complete", stats.running));
+        } else if stats.failed > 0 {
+            suggestions.push(format!("Address {} failed task(s)", stats.failed));
+        }
+    }
+
+    // Generate summary
+    let summary = generate_phase_summary(phase, &file_deliverables, has_repository, &task_stats, completion_percentage);
+
+    PhaseChecklist {
+        phase: phase.to_string(),
+        file_deliverables,
+        has_repository,
+        repository_required: deliverables.requires_repository,
+        task_stats,
+        completion_percentage,
+        summary,
+        suggestions,
+    }
+}
+
+fn generate_phase_summary(
+    phase: &str,
+    deliverables: &[DeliverableStatus],
+    has_repository: bool,
+    task_stats: &Option<TaskStats>,
+    completion_percentage: u8,
+) -> String {
+    let completed_count = deliverables.iter().filter(|d| d.completed).count();
+    let total_count = deliverables.len();
+
+    match phase {
+        "research" => {
+            if completed_count == 0 {
+                "Research phase needs documentation. Create research notes or competitor analysis.".to_string()
+            } else {
+                format!("{}/{} research documents created. Consider transitioning to Specify phase.", completed_count, total_count)
+            }
+        }
+        "specify" => {
+            let has_required = deliverables.iter()
+                .filter(|d| d.priority == FilePriority::Required)
+                .all(|d| d.completed);
+
+            if !has_required {
+                "Specify phase requires a Requirements Document before transitioning.".to_string()
+            } else if completion_percentage >= 66 {
+                "Specifications are ready. Consider transitioning to Plan phase.".to_string()
+            } else {
+                format!("{}/{} specification documents created.", completed_count, total_count)
+            }
+        }
+        "plan" => {
+            let has_task_breakdown = deliverables.iter()
+                .any(|d| d.template_id == "task-breakdown" && d.completed);
+
+            if !has_task_breakdown {
+                "Plan phase requires a Task Breakdown document.".to_string()
+            } else if !has_repository {
+                "Repository not configured. Configure a repository before Execute phase.".to_string()
+            } else {
+                "Planning complete. Ready to transition to Execute phase.".to_string()
+            }
+        }
+        "execute" => {
+            if let Some(stats) = task_stats {
+                if stats.total == 0 {
+                    "No tasks created. Create tasks from the Task Breakdown document.".to_string()
+                } else if stats.done == stats.total {
+                    "All tasks complete! Ready for Review phase.".to_string()
+                } else {
+                    format!("{}/{} tasks completed ({}% done)", stats.done, stats.total,
+                        if stats.total > 0 { (stats.done * 100) / stats.total } else { 0 })
+                }
+            } else {
+                "Execute phase in progress.".to_string()
+            }
+        }
+        "review" => {
+            let has_release_notes = deliverables.iter()
+                .any(|d| d.template_id == "release-notes" && d.completed);
+
+            if !has_release_notes {
+                "Review phase requires Release Notes before completion.".to_string()
+            } else {
+                "Review documentation complete. Contract can be marked as done.".to_string()
+            }
+        }
+        _ => format!("Phase {} - {}% complete", phase, completion_percentage),
+    }
+}
+
+/// Check if phase targets are met for transition
+pub fn check_phase_completion(
+    phase: &str,
+    files: &[FileInfo],
+    tasks: &[TaskInfo],
+    has_repository: bool,
+) -> bool {
+    let checklist = get_phase_checklist(phase, files, tasks, has_repository);
+
+    // Check required files are complete
+    let required_files_complete = checklist.file_deliverables.iter()
+        .filter(|d| d.priority == FilePriority::Required)
+        .all(|d| d.completed);
+
+    // Check repository if required
+    let repository_ok = !checklist.repository_required || checklist.has_repository;
+
+    // Check tasks if in execute phase
+    let tasks_ok = if let Some(stats) = &checklist.task_stats {
+        stats.total > 0 && stats.done == stats.total
+    } else {
+        true
+    };
+
+    required_files_complete && repository_ok && tasks_ok
+}
+
+/// Format checklist as markdown for LLM context
+pub fn format_checklist_markdown(checklist: &PhaseChecklist) -> String {
+    let mut md = format!("## Phase Progress ({} Phase)\n\n", capitalize(&checklist.phase));
+
+    // File deliverables
+    md.push_str("### Deliverables\n");
+    for status in &checklist.file_deliverables {
+        let check = if status.completed { "+" } else { "-" };
+        let priority_label = match status.priority {
+            FilePriority::Required => " (required)",
+            FilePriority::Recommended => " (recommended)",
+            FilePriority::Optional => " (optional)",
+        };
+
+        if status.completed {
+            md.push_str(&format!("[{}] {} - \"{}\"\n", check, status.name, status.actual_name.as_deref().unwrap_or("created")));
+        } else {
+            md.push_str(&format!("[{}] {}{}\n", check, status.name, priority_label));
+        }
+    }
+
+    // Repository status
+    if checklist.repository_required {
+        let check = if checklist.has_repository { "+" } else { "-" };
+        md.push_str(&format!("[{}] Repository configured (required)\n", check));
+    }
+
+    // Task stats for execute phase
+    if let Some(ref stats) = checklist.task_stats {
+        md.push_str(&format!("\n### Task Progress\n"));
+        md.push_str(&format!("- Total: {}\n", stats.total));
+        md.push_str(&format!("- Done: {}\n", stats.done));
+        if stats.pending > 0 {
+            md.push_str(&format!("- Pending: {}\n", stats.pending));
+        }
+        if stats.running > 0 {
+            md.push_str(&format!("- Running: {}\n", stats.running));
+        }
+        if stats.failed > 0 {
+            md.push_str(&format!("- Failed: {}\n", stats.failed));
+        }
+    }
+
+    // Summary
+    md.push_str(&format!("\n**Status**: {} ({}% complete)\n", checklist.summary, checklist.completion_percentage));
+
+    // Suggestions
+    if !checklist.suggestions.is_empty() {
+        md.push_str("\n**Next Steps**:\n");
+        for suggestion in &checklist.suggestions {
+            md.push_str(&format!("- {}\n", suggestion));
+        }
+    }
+
+    md
+}
+
+fn capitalize(s: &str) -> String {
+    let mut chars = s.chars();
+    match chars.next() {
+        None => String::new(),
+        Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_phase_deliverables() {
+        let research = get_phase_deliverables("research");
+        assert_eq!(research.phase, "research");
+        assert!(!research.requires_repository);
+        assert_eq!(research.recommended_files.len(), 3);
+
+        let plan = get_phase_deliverables("plan");
+        assert!(plan.requires_repository);
+        assert!(plan.recommended_files.iter().any(|f| f.template_id == "task-breakdown"));
+    }
+
+    #[test]
+    fn test_phase_checklist_empty() {
+        let checklist = get_phase_checklist("research", &[], &[], false);
+        assert_eq!(checklist.completion_percentage, 0);
+        assert!(!checklist.suggestions.is_empty());
+    }
+
+    #[test]
+    fn test_check_phase_completion() {
+        let files = vec![
+            FileInfo {
+                id: Uuid::new_v4(),
+                name: "Requirements Document".to_string(),
+                contract_phase: Some("specify".to_string()),
+            },
+        ];
+
+        // Specify phase has required file
+        let complete = check_phase_completion("specify", &files, &[], false);
+        assert!(complete);
+    }
+}