path: root/makima/src/orchestration/directive.rs

//! Directive orchestrator — automates the full directive lifecycle.
//!
//! Runs as a background loop, polling every 15s to:
//! 1. Plan: active directives with no steps → spawn planning task
//! 2. Execute: ready steps → spawn execution tasks
//! 3. Monitor: detect task completion → update step status, advance DAG
//! 4. Re-plan: goal updated → spawn new planning task

use sqlx::PgPool;
use uuid::Uuid;

use base64::Engine;

use crate::db::models::{CreateContractRequest, CreateTaskRequest, UpdateContractRequest, UpdateTaskRequest};
use crate::db::repository;
use crate::server::state::{DaemonCommand, SharedState};

pub struct DirectiveOrchestrator {
    pool: PgPool,
    state: SharedState,
}

impl DirectiveOrchestrator {
    pub fn new(pool: PgPool, state: SharedState) -> Self {
        Self { pool, state }
    }

    /// Run one orchestration tick — called every 15s.
    pub async fn tick(&mut self) -> Result<(), anyhow::Error> {
        if let Err(e) = self.phase_planning().await {
            tracing::warn!(error = %e, "Directive phase_planning failed, continuing to next phase");
        }
        if let Err(e) = self.phase_execution().await {
            tracing::warn!(error = %e, "Directive phase_execution failed, continuing to next phase");
        }
        if let Err(e) = self.phase_monitoring().await {
            tracing::warn!(error = %e, "Directive phase_monitoring failed, continuing to next phase");
        }
        if let Err(e) = self.phase_replanning().await {
            tracing::warn!(error = %e, "Directive phase_replanning failed, continuing to next phase");
        }
        if let Err(e) = self.phase_completion().await {
            tracing::warn!(error = %e, "Directive phase_completion failed");
        }
        Ok(())
    }

    /// Phase 1: Active directives with no steps and no orchestrator task → spawn planning task.
    async fn phase_planning(&self) -> Result<(), anyhow::Error> {
        let directives = repository::get_directives_needing_planning(&self.pool).await?;

        for directive in directives {
            tracing::info!(
                directive_id = %directive.id,
                title = %directive.title,
                "Directive needs planning — spawning planning task"
            );

            let plan = build_planning_prompt(&directive, &[], 1, &[]);

            if let Err(e) = self
                .spawn_orchestrator_task(
                    directive.id,
                    directive.owner_id,
                    format!("Plan: {}", directive.title),
                    plan,
                    directive.repository_url.as_deref(),
                    directive.base_branch.as_deref(),
                )
                .await
            {
                tracing::warn!(
                    directive_id = %directive.id,
                    error = %e,
                    "Failed to spawn planning task"
                );
            }
        }
        Ok(())
    }

    /// Phase 2: Ready steps with no task → create execution task and dispatch.
    /// Also retries pending directive tasks that weren't dispatched previously.
    async fn phase_execution(&self) -> Result<(), anyhow::Error> {
        // Create tasks for ready steps
        let steps = repository::get_ready_steps_for_dispatch(&self.pool).await?;

        for step in steps {
            // If the step has a contract_type, create a contract instead of a standalone task
            if step.contract_type.is_some() {
                tracing::info!(
                    step_id = %step.step_id,
                    directive_id = %step.directive_id,
                    step_name = %step.step_name,
                    contract_type = ?step.contract_type,
                    "Spawning contract for contract-backed step"
                );

                match self
                    .spawn_step_contract(
                        step.step_id,
                        step.directive_id,
                        step.owner_id,
                        &step.step_name,
                        step.step_description.as_deref(),
                        step.task_plan.as_deref(),
                        step.contract_type.as_deref().unwrap_or("simple"),
                        step.repository_url.as_deref(),
                        step.base_branch.as_deref(),
                    )
                    .await
                {
                    Ok(()) => {}
                    Err(e) => {
                        tracing::warn!(
                            step_id = %step.step_id,
                            error = %e,
                            "Failed to spawn contract for step"
                        );
                    }
                }
                continue;
            }

            tracing::info!(
                step_id = %step.step_id,
                directive_id = %step.directive_id,
                step_name = %step.step_name,
                "Dispatching execution task for ready step"
            );

            // Resolve dependency steps to their task IDs for worktree continuation
            let dep_tasks = match repository::get_step_dependency_tasks(&self.pool, &step.depends_on).await {
                Ok(deps) => deps,
                Err(e) => {
                    tracing::warn!(step_id = %step.step_id, error = %e, "Failed to resolve step dependencies — skipping step");
                    continue;
                }
            };
            let mut continue_from_task_id = dep_tasks.first().map(|d| d.task_id);

            // If no dependency tasks resolved, try to continue from the last completed step's worktree.
            // We never use pr_branch as base because it may have been deleted after PR merge.
            let effective_base_branch = if continue_from_task_id.is_none() {
                match repository::get_last_completed_step_task_id(
                    &self.pool,
                    step.directive_id,
                )
                .await
                {
                    Ok(Some(task_id)) => {
                        tracing::info!(
                            step_id = %step.step_id,
                            continue_from = %task_id,
                            "Step has no deps — continuing from last completed task"
                        );
                        continue_from_task_id = Some(task_id);
                        step.base_branch.as_deref()
                    }
                    _ => step.base_branch.as_deref(),
                }
            } else {
                step.base_branch.as_deref()
            };

            let task_plan = step
                .task_plan
                .as_deref()
                .unwrap_or("Execute the step described below.");

            // Build merge instructions for additional dependencies (beyond the first)
            let merge_preamble = if dep_tasks.len() > 1 {
                use crate::daemon::worktree::{sanitize_name, short_uuid};
                let merge_lines: Vec<String> = dep_tasks[1..]
                    .iter()
                    .map(|d| {
                        let branch = format!(
                            "makima/task-{}-{}",
                            sanitize_name(&d.task_name),
                            short_uuid(d.task_id)
                        );
                        format!("git merge origin/{} --no-edit", branch)
                    })
                    .collect();
                format!(
                    "IMPORTANT — MERGE DEPENDENCY BRANCHES FIRST:\n\
                     This step continues from one dependency's worktree, but also depends on \
                     additional branches. Before starting work, run:\n\
                     ```\ngit fetch origin\n{}\n```\n\
                     Resolve any merge conflicts sensibly, then proceed.\n\n",
                    merge_lines.join("\n"),
                )
            } else {
                String::new()
            };

            let manual_mode_appendix = if step.reconcile_mode == "manual" {
                "\n\nIMPORTANT: This directive is in MANUAL reconcile mode. Before making assumptions or proceeding with implementation choices, you MUST ask clarification questions using:\n\
                 \x20 makima directive ask \"<question>\" --phaseguard\n\
                 Ask multiple targeted questions about requirements, edge cases, and design decisions. Wait for answers before writing code. Do not proceed until you have clear direction from the user."
            } else {
                ""
            };

            let plan = format!(
                "You are executing a step in directive \"{directive_title}\".\n\n\
                 STEP: {step_name}\n\
                 DESCRIPTION: {description}\n\n\
                 {merge_preamble}\
                 INSTRUCTIONS:\n{task_plan}\n\
                 When done, the system will automatically mark this step as completed.\n\
                 If you cannot complete the task, report the failure clearly.\n\n\
                 If you need clarification or encounter a decision that requires user input, you can ask:\n\
                 \x20 makima directive ask \"Your question\" --phaseguard{manual_mode_appendix}",
                directive_title = step.directive_title,
                step_name = step.step_name,
                description = step.step_description.as_deref().unwrap_or("(none)"),
                merge_preamble = merge_preamble,
                task_plan = task_plan,
                manual_mode_appendix = manual_mode_appendix,
            );

            match self
                .spawn_step_task(
                    step.step_id,
                    step.directive_id,
                    step.owner_id,
                    format!("{}: {}", step.directive_title, step.step_name),
                    plan,
                    step.repository_url.as_deref(),
                    effective_base_branch,
                    continue_from_task_id,
                )
                .await
            {
                Ok(()) => {}
                Err(e) => {
                    tracing::warn!(
                        step_id = %step.step_id,
                        error = %e,
                        "Failed to spawn execution task for step"
                    );
                }
            }
        }

        // Retry pending directive tasks that weren't dispatched
        let pending = repository::get_pending_directive_tasks(&self.pool).await?;
        for task in pending {
            if self
                .try_dispatch_task(task.id, task.owner_id, &task.name, &task.plan, task.version)
                .await
            {
                // Task dispatched — mark its step as running if it has one
                if let Some(step_id) = task.directive_step_id {
                    let _ = repository::set_step_running(&self.pool, step_id).await;
                }
            }
        }

        Ok(())
    }

    /// Phase 3: Monitor running steps and orchestrator tasks.
    async fn phase_monitoring(&self) -> Result<(), anyhow::Error> {
        // Check contract-backed running steps first
        let contract_steps = repository::get_running_steps_with_contracts(&self.pool).await?;

        for step in contract_steps {
            if let Err(e) = async {
                match step.contract_status.as_str() {
                    "completed" | "archived" => {
                        tracing::info!(
                            step_id = %step.step_id,
                            directive_id = %step.directive_id,
                            contract_id = %step.contract_id,
                            contract_status = %step.contract_status,
                            "Contract-backed step contract completed — updating step to completed"
                        );
                        let update = crate::db::models::UpdateDirectiveStepRequest {
                            status: Some("completed".to_string()),
                            ..Default::default()
                        };
                        repository::update_directive_step(&self.pool, step.step_id, update).await?;

                        // Mark linked orders as done
                        if let Ok(linked_orders) = repository::get_orders_by_step_id(&self.pool, step.step_id).await {
                            for order in linked_orders {
                                if order.status != "done" && order.status != "archived" {
                                    let order_update = crate::db::models::UpdateOrderRequest {
                                        status: Some("done".to_string()),
                                        ..Default::default()
                                    };
                                    let _ = repository::update_order(&self.pool, order.owner_id, order.id, order_update).await;
                                }
                            }
                        }

                        repository::advance_directive_ready_steps(&self.pool, step.directive_id)
                            .await?;
                        repository::check_directive_idle(&self.pool, step.directive_id).await?;
                    }
                    "active" => {
                        // Contract still active — check if the supervisor has failed
                        // by looking at whether there are any failed tasks with no active tasks remaining
                        tracing::debug!(
                            step_id = %step.step_id,
                            contract_id = %step.contract_id,
                            contract_phase = %step.contract_phase,
                            "Contract-backed step still active — monitoring"
                        );
                    }
                    _ => {
                        // Unknown status — log and skip
                        tracing::debug!(
                            step_id = %step.step_id,
                            contract_id = %step.contract_id,
                            contract_status = %step.contract_status,
                            "Contract-backed step in unexpected status"
                        );
                    }
                }
                Ok::<(), anyhow::Error>(())
            }.await {
                tracing::warn!(step_id = %step.step_id, error = %e, "Error processing contract-backed step — continuing");
            }
        }

        // Check task-backed running steps (excludes contract-backed steps)
        let running = repository::get_running_steps_with_tasks(&self.pool).await?;

        for step in running {
            if let Err(e) = async {
                match step.task_status.as_str() {
                    "completed" | "merged" | "done" => {
                        tracing::info!(
                            step_id = %step.step_id,
                            directive_id = %step.directive_id,
                            task_id = %step.task_id,
                            "Step task completed — updating step to completed"
                        );
                        let update = crate::db::models::UpdateDirectiveStepRequest {
                            status: Some("completed".to_string()),
                            ..Default::default()
                        };
                        repository::update_directive_step(&self.pool, step.step_id, update).await?;

                        // Mark linked orders as done
                        if let Ok(linked_orders) = repository::get_orders_by_step_id(&self.pool, step.step_id).await {
                            for order in linked_orders {
                                if order.status != "done" && order.status != "archived" {
                                    let order_update = crate::db::models::UpdateOrderRequest {
                                        status: Some("done".to_string()),
                                        ..Default::default()
                                    };
                                    let _ = repository::update_order(&self.pool, order.owner_id, order.id, order_update).await;
                                }
                            }
                        }

                        repository::advance_directive_ready_steps(&self.pool, step.directive_id)
                            .await?;
                        repository::check_directive_idle(&self.pool, step.directive_id).await?;
                    }
                    "failed" | "interrupted" => {
                        tracing::warn!(
                            step_id = %step.step_id,
                            directive_id = %step.directive_id,
                            task_id = %step.task_id,
                            task_status = %step.task_status,
                            "Step task failed — updating step to failed"
                        );
                        let update = crate::db::models::UpdateDirectiveStepRequest {
                            status: Some("failed".to_string()),
                            ..Default::default()
                        };
                        repository::update_directive_step(&self.pool, step.step_id, update).await?;
                        repository::advance_directive_ready_steps(&self.pool, step.directive_id)
                            .await?;
                        repository::check_directive_idle(&self.pool, step.directive_id).await?;
                    }
                    "paused" => {
                        tracing::debug!(
                            step_id = %step.step_id,
                            directive_id = %step.directive_id,
                            task_id = %step.task_id,
                            "Step task paused (waiting for user response) — keeping step running"
                        );
                    }
                    _ => {}
                }
                Ok::<(), anyhow::Error>(())
            }.await {
                tracing::warn!(step_id = %step.step_id, error = %e, "Error processing running step — continuing");
            }
        }

        // Check orchestrator (planning) tasks
        let orch_tasks = repository::get_orchestrator_tasks_to_check(&self.pool).await?;

        for orch in orch_tasks {
            if let Err(e) = async {
                match orch.task_status.as_str() {
                    "completed" | "merged" | "done" => {
                        tracing::info!(
                            directive_id = %orch.directive_id,
                            task_id = %orch.orchestrator_task_id,
                            "Planning task completed — clearing orchestrator task"
                        );
                        repository::clear_orchestrator_task(&self.pool, orch.directive_id).await?;
                        repository::advance_directive_ready_steps(&self.pool, orch.directive_id)
                            .await?;
                    }
                    "failed" | "interrupted" => {
                        tracing::warn!(
                            directive_id = %orch.directive_id,
                            task_id = %orch.orchestrator_task_id,
                            "Planning task failed — pausing directive"
                        );
                        repository::clear_orchestrator_task(&self.pool, orch.directive_id).await?;
                        repository::set_directive_status(
                            &self.pool,
                            orch.owner_id,
                            orch.directive_id,
                            "paused",
                        )
                        .await?;
                    }
                    _ => {}
                }
                Ok::<(), anyhow::Error>(())
            }.await {
                tracing::warn!(directive_id = %orch.directive_id, error = %e, "Error processing orchestrator task — continuing");
            }
        }

        Ok(())
    }

    /// Phase 4: Re-planning — goal updated after latest step creation.
    async fn phase_replanning(&self) -> Result<(), anyhow::Error> {
        let directives = repository::get_directives_needing_replanning(&self.pool).await?;

        for directive in directives {
            tracing::info!(
                directive_id = %directive.id,
                title = %directive.title,
                "Directive goal updated — spawning re-planning task"
            );

            let existing_steps =
                repository::list_directive_steps(&self.pool, directive.id).await?;
            let generation =
                repository::get_directive_max_generation(&self.pool, directive.id).await? + 1;
            let goal_history =
                repository::get_directive_goal_history(&self.pool, directive.id, 3).await?;

            let plan =
                build_planning_prompt(&directive, &existing_steps, generation, &goal_history);

            if let Err(e) = self
                .spawn_orchestrator_task(
                    directive.id,
                    directive.owner_id,
                    format!("Re-plan: {}", directive.title),
                    plan,
                    directive.repository_url.as_deref(),
                    directive.base_branch.as_deref(),
                )
                .await
            {
                tracing::warn!(
                    directive_id = %directive.id,
                    title = %directive.title,
                    "Directive goal updated — spawning re-planning task"
                );

                // If directive already has a PR, remove completed steps that were included in it
                if directive.pr_url.is_some() || directive.pr_branch.is_some() {
                    match remove_already_merged_steps(&self.pool, directive.id).await {
                        Ok(count) if count > 0 => {
                            tracing::info!(
                                directive_id = %directive.id,
                                removed = count,
                                "Auto-removed completed steps already included in PR before replanning"
                            );
                        }
                        Err(e) => {
                            tracing::warn!(
                                directive_id = %directive.id,
                                error = %e,
                                "Failed to auto-remove merged steps before replanning"
                            );
                        }
                        _ => {}
                    }
                }

                let existing_steps =
                    repository::list_directive_steps(&self.pool, directive.id).await?;
                let generation =
                    repository::get_directive_max_generation(&self.pool, directive.id).await? + 1;
                let goal_history =
                    repository::get_directive_goal_history(&self.pool, directive.id, 3).await?;

                let plan =
                    build_planning_prompt(&directive, &existing_steps, generation, &goal_history);

                if let Err(e) = self
                    .spawn_orchestrator_task(
                        directive.id,
                        directive.owner_id,
                        format!("Re-plan: {}", directive.title),
                        plan,
                        directive.repository_url.as_deref(),
                        directive.base_branch.as_deref(),
                    )
                    .await
                {
                    tracing::warn!(
                        directive_id = %directive.id,
                        error = %e,
                        "Failed to spawn re-planning task"
                    );
                }
                Ok::<(), anyhow::Error>(())
            }.await {
                tracing::warn!(directive_id = %directive.id, error = %e, "Error in re-planning directive — continuing");
            }
        }
        Ok(())
    }

    /// Spawn a planning/re-planning task and assign it as the directive's orchestrator task.
    async fn spawn_orchestrator_task(
        &self,
        directive_id: Uuid,
        owner_id: Uuid,
        name: String,
        plan: String,
        repo_url: Option<&str>,
        base_branch: Option<&str>,
    ) -> Result<(), anyhow::Error> {
        let req = CreateTaskRequest {
            contract_id: None,
            name,
            description: Some("Directive planning task".to_string()),
            plan,
            parent_task_id: None,
            is_supervisor: false,
            priority: 0,
            repository_url: repo_url.map(|s| s.to_string()),
            base_branch: base_branch.map(|s| s.to_string()),
            target_branch: None,
            merge_mode: None,
            target_repo_path: None,
            completion_action: None,
            continue_from_task_id: None,
            copy_files: None,
            checkpoint_sha: None,
            branched_from_task_id: None,
            conversation_history: None,
            supervisor_worktree_task_id: None,
            directive_id: Some(directive_id),
            directive_step_id: None,
        };

        let task = repository::create_task_for_owner(&self.pool, owner_id, req).await?;

        repository::assign_orchestrator_task(&self.pool, directive_id, task.id).await?;

        // Cancel any old planning tasks for this directive (superseded by the new one)
        let cancelled =
            repository::cancel_old_planning_tasks(&self.pool, directive_id, task.id).await?;
        if cancelled > 0 {
            tracing::info!(
                directive_id = %directive_id,
                cancelled_count = cancelled,
                "Cancelled old planning tasks superseded by new plan"
            );
        }

        // Try to dispatch to a daemon
        self.try_dispatch_task(task.id, owner_id, &task.name, &task.plan, task.version).await;

        Ok(())
    }

    /// Spawn an execution task for a step.
    /// Links the task to the step but only marks the step as 'running' once dispatched.
    async fn spawn_step_task(
        &self,
        step_id: Uuid,
        directive_id: Uuid,
        owner_id: Uuid,
        name: String,
        plan: String,
        repo_url: Option<&str>,
        base_branch: Option<&str>,
        continue_from_task_id: Option<Uuid>,
    ) -> Result<(), anyhow::Error> {
        let req = CreateTaskRequest {
            contract_id: None,
            name,
            description: Some("Directive step execution task".to_string()),
            plan,
            parent_task_id: None,
            is_supervisor: false,
            priority: 0,
            repository_url: repo_url.map(|s| s.to_string()),
            base_branch: base_branch.map(|s| s.to_string()),
            target_branch: None,
            merge_mode: None,
            target_repo_path: None,
            completion_action: Some("branch".to_string()),
            continue_from_task_id,
            copy_files: None,
            checkpoint_sha: None,
            branched_from_task_id: None,
            conversation_history: None,
            supervisor_worktree_task_id: None,
            directive_id: Some(directive_id),
            directive_step_id: Some(step_id),
        };

        let task = repository::create_task_for_owner(&self.pool, owner_id, req).await?;

        // Link the task to the step (sets task_id) but keep step as 'ready' for now
        repository::link_task_to_step(&self.pool, step_id, task.id).await?;

        // Only mark step as 'running' if we can actually dispatch the task
        if self
            .try_dispatch_task(task.id, owner_id, &task.name, &task.plan, task.version)
            .await
        {
            repository::set_step_running(&self.pool, step_id).await?;
        }

        Ok(())
    }

    /// Spawn a contract for a contract-backed step.
    /// Creates a contract, adds the directive's repository to it, links it to the step,
    /// creates a supervisor task, and marks the step as running.
    async fn spawn_step_contract(
        &self,
        step_id: Uuid,
        directive_id: Uuid,
        owner_id: Uuid,
        step_name: &str,
        step_description: Option<&str>,
        task_plan: Option<&str>,
        contract_type: &str,
        repo_url: Option<&str>,
        base_branch: Option<&str>,
    ) -> Result<(), anyhow::Error> {
        // Build contract description from step info
        let description = match (step_description, task_plan) {
            (Some(desc), Some(plan)) => Some(format!("{}\n\n{}", desc, plan)),
            (Some(desc), None) => Some(desc.to_string()),
            (None, Some(plan)) => Some(plan.to_string()),
            (None, None) => None,
        };

        // Create the contract
        let contract_req = CreateContractRequest {
            name: step_name.to_string(),
            description,
            contract_type: Some(contract_type.to_string()),
            template_id: None,
            initial_phase: None,
            autonomous_loop: Some(true),
            phase_guard: None,
            local_only: None,
            auto_merge_local: None,
        };

        let contract = repository::create_contract_for_owner(&self.pool, owner_id, contract_req).await?;

        tracing::info!(
            step_id = %step_id,
            contract_id = %contract.id,
            contract_type = %contract.contract_type,
            "Created contract for directive step"
        );

        // Link the contract to the step
        repository::link_contract_to_step(&self.pool, step_id, contract.id).await?;

        // Add the directive's repository to the contract (if available)
        if let Some(url) = repo_url {
            if let Err(e) = repository::add_remote_repository(
                &self.pool,
                contract.id,
                step_name,
                url,
                true, // is_primary
            )
            .await
            {
                tracing::warn!(
                    contract_id = %contract.id,
                    error = %e,
                    "Failed to add repository to contract — continuing without it"
                );
            }
        }

        // Create supervisor task for the contract (following the pattern from contract handlers)
        let supervisor_name = format!("{} Supervisor", step_name);
        let supervisor_plan = format!(
            "You are the supervisor for contract '{}'. Your goal is to drive this contract to completion.\n\n{}",
            step_name,
            contract.description.as_deref().unwrap_or("No description provided.")
        );

        let supervisor_req = CreateTaskRequest {
            name: supervisor_name.clone(),
            description: None,
            plan: supervisor_plan.clone(),
            repository_url: repo_url.map(|s| s.to_string()),
            base_branch: base_branch.map(|s| s.to_string()),
            target_branch: None,
            parent_task_id: None,
            contract_id: Some(contract.id),
            target_repo_path: None,
            completion_action: None,
            continue_from_task_id: None,
            copy_files: None,
            is_supervisor: true,
            checkpoint_sha: None,
            priority: 0,
            merge_mode: None,
            branched_from_task_id: None,
            conversation_history: None,
            supervisor_worktree_task_id: None,
            directive_id: Some(directive_id),
            directive_step_id: Some(step_id),
        };

        let supervisor_task = repository::create_task_for_owner(&self.pool, owner_id, supervisor_req).await?;

        tracing::info!(
            contract_id = %contract.id,
            supervisor_task_id = %supervisor_task.id,
            "Created supervisor task for contract-backed step"
        );

        // Link supervisor task to contract
        let update_req = UpdateContractRequest {
            supervisor_task_id: Some(supervisor_task.id),
            version: Some(contract.version),
            ..Default::default()
        };
        if let Err(e) = repository::update_contract_for_owner(&self.pool, contract.id, owner_id, update_req).await {
            tracing::warn!(
                contract_id = %contract.id,
                error = %e,
                "Failed to link supervisor task to contract"
            );
        }

        // Try to dispatch the supervisor task to a daemon
        if self
            .try_dispatch_task(supervisor_task.id, owner_id, &supervisor_task.name, &supervisor_task.plan, supervisor_task.version)
            .await
        {
            repository::set_step_running(&self.pool, step_id).await?;
        } else {
            // Even if dispatch fails, mark step as running since contract is created.
            // The supervisor task will be retried by the pending task retry logic.
            repository::set_step_running(&self.pool, step_id).await?;
        }

        Ok(())
    }

    /// Try to dispatch a task to an available daemon. Returns true if dispatched.
    async fn try_dispatch_task(
        &self,
        task_id: Uuid,
        owner_id: Uuid,
        task_name: &str,
        plan: &str,
        version: i32,
    ) -> bool {
        let Some(daemon_id) = self.state.find_alternative_daemon(owner_id, &[]) else {
            tracing::info!(
                task_id = %task_id,
                "No daemon available for directive task — leaving pending for retry"
            );
            return false;
        };

        // Update task status to starting and assign daemon
        let update_req = UpdateTaskRequest {
            status: Some("starting".to_string()),
            daemon_id: Some(daemon_id),
            version: Some(version),
            ..Default::default()
        };

        match repository::update_task_for_owner(&self.pool, task_id, owner_id, update_req).await {
            Ok(Some(updated_task)) => {
                // Load patch data from continue_from task for worktree recovery
                let (patch_data, patch_base_sha) = if let Some(from_id) = updated_task.continue_from_task_id {
                    match repository::get_latest_checkpoint_patch(&self.pool, from_id).await {
                        Ok(Some(patch)) => {
                            let encoded = base64::engine::general_purpose::STANDARD.encode(&patch.patch_data);
                            (Some(encoded), Some(patch.base_commit_sha))
                        }
                        _ => (None, None),
                    }
                } else {
                    (None, None)
                };

                let command = DaemonCommand::SpawnTask {
                    task_id,
                    task_name: task_name.to_string(),
                    plan: plan.to_string(),
                    repo_url: updated_task.repository_url.clone(),
                    base_branch: updated_task.base_branch.clone(),
                    target_branch: updated_task.target_branch.clone(),
                    parent_task_id: None,
                    depth: 0,
                    is_orchestrator: false,
                    target_repo_path: None,
                    completion_action: updated_task.completion_action.clone(),
                    continue_from_task_id: updated_task.continue_from_task_id,
                    copy_files: None,
                    contract_id: None,
                    is_supervisor: false,
                    autonomous_loop: false,
                    resume_session: false,
                    conversation_history: None,
                    patch_data,
                    patch_base_sha,
                    local_only: false,
                    auto_merge_local: false,
                    supervisor_worktree_task_id: None,
                    directive_id: updated_task.directive_id,
                };

                if let Err(e) = self.state.send_daemon_command(daemon_id, command).await {
                    tracing::warn!(
                        task_id = %task_id,
                        daemon_id = %daemon_id,
                        error = %e,
                        "Failed to send SpawnTask to daemon for directive task"
                    );
                    return false;
                } else {
                    tracing::info!(
                        task_id = %task_id,
                        daemon_id = %daemon_id,
                        "Dispatched directive task to daemon"
                    );
                    return true;
                }
            }
            Ok(None) => {
                tracing::warn!(task_id = %task_id, "Task not found when trying to dispatch");
            }
            Err(e) => {
                tracing::warn!(task_id = %task_id, error = %e, "Failed to update task for dispatch");
            }
        }
        false
    }

    /// Phase 5: Completion — spawn PR-creation tasks for idle directives.
    async fn phase_completion(&self) -> Result<(), anyhow::Error> {
        // Part 1: Spawn completion tasks for idle directives
        let directives = repository::get_idle_directives_needing_completion(&self.pool).await?;

        for directive in directives {
            if let Err(e) = async {
                // Skip if already claimed (completion_task_id is set)
                if directive.completion_task_id.is_some() {
                    tracing::debug!(
                        directive_id = %directive.id,
                        "Directive already has a completion task — skipping"
                    );
                    return Ok::<(), anyhow::Error>(());
                }

                tracing::info!(
                    directive_id = %directive.id,
                    title = %directive.title,
                    "Directive idle — spawning completion task for PR"
                );

                let step_tasks = repository::get_completed_step_tasks(&self.pool, directive.id).await?;
                if step_tasks.is_empty() {
                    return Ok(());
                }

                let base_branch = directive
                    .base_branch
                    .as_deref()
                    .unwrap_or("main");

                let directive_branch = format!(
                    "makima/directive-{}-{}",
                    crate::daemon::worktree::sanitize_name(&directive.title),
                    crate::daemon::worktree::short_uuid(directive.id),
                );

                let step_branches: Vec<String> = step_tasks
                    .iter()
                    .map(|st| {
                        format!(
                            "makima/{}-{}",
                            crate::daemon::worktree::sanitize_name(&st.task_name),
                            crate::daemon::worktree::short_uuid(st.task_id),
                        )
                    })
                    .collect();

                let prompt = build_completion_prompt(
                    &directive,
                    &step_tasks,
                    &step_branches,
                    &directive_branch,
                    base_branch,
                );

                // Create the task FIRST so we have a real task ID for the FK
                match self
                    .spawn_completion_task(
                        directive.id,
                        directive.owner_id,
                        format!("PR: {}", directive.title),
                        prompt,
                        directive.repository_url.as_deref(),
                        directive.base_branch.as_deref(),
                    )
                    .await
                {
                    Ok(task_id) => {
                        // Atomically claim with the REAL task ID (satisfies FK constraint)
                        let claimed = repository::claim_directive_for_completion(
                            &self.pool,
                            directive.id,
                            task_id,
                        )
                        .await?;

                        if !claimed {
                            tracing::debug!(
                                directive_id = %directive.id,
                                "Directive already claimed for completion — task will be orphaned"
                            );
                            return Ok(());
                        }

                        let update = crate::db::models::UpdateDirectiveRequest {
                            pr_branch: Some(directive_branch.clone()),
                            ..Default::default()
                        };
                        let _ = repository::update_directive_for_owner(
                            &self.pool,
                            directive.owner_id,
                            directive.id,
                            update,
                        )
                        .await;
                    }
                    Err(e) => {
                        tracing::warn!(
                            directive_id = %directive.id,
                            error = %e,
                            "Failed to spawn completion task"
                        );
                    }
                }
                Ok(())
            }.await {
                tracing::warn!(directive_id = %directive.id, error = %e, "Error processing directive completion — continuing");
            }
        }

        // Part 2: Monitor completion tasks
        let checks = repository::get_completion_tasks_to_check(&self.pool).await?;

        for check in checks {
            if let Err(e) = async {
                match check.task_status.as_str() {
                    "completed" | "merged" | "done" => {
                        tracing::info!(
                            directive_id = %check.directive_id,
                            task_id = %check.completion_task_id,
                            "Completion task finished"
                        );

                        if check.pr_url.is_none() {
                            match self.extract_pr_url_from_task(check.completion_task_id).await {
                                Ok(Some(url)) => {
                                    tracing::info!(
                                        directive_id = %check.directive_id,
                                        pr_url = %url,
                                        "Extracted PR URL from completion task output"
                                    );
                                    let update = crate::db::models::UpdateDirectiveRequest {
                                        pr_url: Some(url),
                                        ..Default::default()
                                    };
                                    let _ = repository::update_directive_for_owner(
                                        &self.pool,
                                        check.owner_id,
                                        check.directive_id,
                                        update,
                                    )
                                    .await;
                                }
                                Ok(None) => {
                                    if check.task_name.starts_with("Verify PR:") {
                                        tracing::warn!(
                                            directive_id = %check.directive_id,
                                            task_id = %check.completion_task_id,
                                            "Verification task finished but no PR URL found — marking directive completed"
                                        );
                                        let update = crate::db::models::UpdateDirectiveRequest {
                                            status: Some("archived".to_string()),
                                            ..Default::default()
                                        };
                                        let _ = repository::update_directive_for_owner(
                                            &self.pool,
                                            check.owner_id,
                                            check.directive_id,
                                            update,
                                        )
                                        .await;
                                    } else {
                                        tracing::warn!(
                                            directive_id = %check.directive_id,
                                            task_id = %check.completion_task_id,
                                            "Completion task finished but no PR URL found — will spawn verifier"
                                        );
                                    }
                                }
                                Err(e) => {
                                    tracing::warn!(
                                        directive_id = %check.directive_id,
                                        error = %e,
                                        "Failed to extract PR URL from completion task output"
                                    );
                                }
                            }
                        }

                        repository::clear_completion_task(&self.pool, check.directive_id).await?;

                        // Auto-remove completed steps that were just included in the PR
                        match remove_already_merged_steps(&self.pool, check.directive_id).await {
                            Ok(count) if count > 0 => {
                                tracing::info!(
                                    directive_id = %check.directive_id,
                                    removed = count,
                                    "Auto-removed completed steps after PR completion"
                                );
                            }
                            Err(e) => {
                                tracing::warn!(
                                    directive_id = %check.directive_id,
                                    error = %e,
                                    "Failed to auto-remove merged steps after completion"
                                );
                            }
                            _ => {}
                        }
                    }
                    "failed" | "interrupted" => {
                        tracing::warn!(
                            directive_id = %check.directive_id,
                            task_id = %check.completion_task_id,
                            "Completion task failed"
                        );
                        repository::clear_completion_task(&self.pool, check.directive_id).await?;
                    }
                    _ => {}
                }
                Ok::<(), anyhow::Error>(())
            }.await {
                tracing::warn!(directive_id = %check.directive_id, error = %e, "Error processing completion task — continuing");
            }
        }

        // Part 3: Spawn verification tasks for directives with pr_branch but no pr_url
        let verify_directives =
            repository::get_directives_needing_verification(&self.pool).await?;

        for directive in verify_directives {
            if let Err(e) = async {
                // Skip if already claimed
                if directive.completion_task_id.is_some() {
                    return Ok::<(), anyhow::Error>(());
                }

                tracing::info!(
                    directive_id = %directive.id,
                    title = %directive.title,
                    "Directive has pr_branch but no pr_url — spawning verification task"
                );

                let pr_branch = directive.pr_branch.as_deref().unwrap_or("unknown");
                let base_branch = directive.base_branch.as_deref().unwrap_or("main");
                let prompt = build_verification_prompt(&directive, pr_branch, base_branch);

                // Create the task FIRST so we have a real task ID for the FK
                match self
                    .spawn_completion_task(
                        directive.id,
                        directive.owner_id,
                        format!("Verify PR: {}", directive.title),
                        prompt,
                        directive.repository_url.as_deref(),
                        directive.base_branch.as_deref(),
                    )
                    .await
                {
                    Ok(task_id) => {
                        // Atomically claim with the REAL task ID (satisfies FK constraint)
                        let claimed = repository::claim_directive_for_completion(
                            &self.pool,
                            directive.id,
                            task_id,
                        )
                        .await?;

                        if !claimed {
                            tracing::debug!(
                                directive_id = %directive.id,
                                "Directive already claimed for verification — task will be orphaned"
                            );
                        }
                    }
                    Err(e) => {
                        tracing::warn!(
                            directive_id = %directive.id,
                            error = %e,
                            "Failed to spawn verification task"
                        );
                    }
                }
                Ok(())
            }.await {
                tracing::warn!(directive_id = %directive.id, error = %e, "Error processing verification directive — continuing");
            }
        }

        Ok(())
    }

    /// Spawn a completion task that creates/updates a PR from step branches.
    async fn spawn_completion_task(
        &self,
        directive_id: Uuid,
        owner_id: Uuid,
        name: String,
        plan: String,
        repo_url: Option<&str>,
        base_branch: Option<&str>,
    ) -> Result<Uuid, anyhow::Error> {
        let req = CreateTaskRequest {
            contract_id: None,
            name,
            description: Some("Directive PR completion task".to_string()),
            plan,
            parent_task_id: None,
            is_supervisor: false,
            priority: 0,
            repository_url: repo_url.map(|s| s.to_string()),
            base_branch: base_branch.map(|s| s.to_string()),
            target_branch: None,
            merge_mode: None,
            target_repo_path: None,
            completion_action: None,
            continue_from_task_id: None,
            copy_files: None,
            checkpoint_sha: None,
            branched_from_task_id: None,
            conversation_history: None,
            supervisor_worktree_task_id: None,
            directive_id: Some(directive_id),
            directive_step_id: None,
        };

        let task = repository::create_task_for_owner(&self.pool, owner_id, req).await?;

        // Try to dispatch to a daemon
        self.try_dispatch_task(task.id, owner_id, &task.name, &task.plan, task.version)
            .await;

        Ok(task.id)
    }

    /// Extract a GitHub PR URL from a completion task's output events.
    /// Searches task output for patterns like `https://github.com/.../pull/123`.
    async fn extract_pr_url_from_task(
        &self,
        task_id: Uuid,
    ) -> Result<Option<String>, anyhow::Error> {
        let events = repository::get_task_output(&self.pool, task_id, Some(500)).await?;

        let pr_url_re = regex::Regex::new(r"https://github\.com/[^/\s]+/[^/\s]+/pull/\d+")?;

        // Search from most recent events backwards for the PR URL
        for event in events.iter().rev() {
            if let Some(ref data) = event.event_data {
                // Check the content field inside event_data JSON
                if let Some(content) = data.get("content").and_then(|c| c.as_str()) {
                    if let Some(m) = pr_url_re.find(content) {
                        return Ok(Some(m.as_str().to_string()));
                    }
                }
                // Also check the raw JSON string representation as fallback
                let data_str = data.to_string();
                if let Some(m) = pr_url_re.find(&data_str) {
                    return Ok(Some(m.as_str().to_string()));
                }
            }
        }

        Ok(None)
    }
}

/// Remove completed directive steps whose branches have already been included
/// in a PR (i.e., the directive has a pr_url or pr_branch set).
/// This prevents duplicate branch merges in subsequent PRs.
pub async fn remove_already_merged_steps(
    pool: &PgPool,
    directive_id: Uuid,
) -> Result<usize, anyhow::Error> {
    let step_tasks = repository::get_completed_step_tasks(pool, directive_id).await?;
    let mut removed = 0;
    for st in &step_tasks {
        if repository::delete_directive_step(pool, st.step_id).await? {
            tracing::info!(
                step_id = %st.step_id,
                step_name = %st.step_name,
                directive_id = %directive_id,
                "Auto-removed completed step (already included in PR)"
            );
            removed += 1;
        }
    }
    Ok(removed)
}

/// Trigger a completion task (PR creation/update) for a directive.
///
/// This is the public entry point used by both the orchestrator tick and the
/// manual "create PR" API handler.  It encapsulates the full flow:
/// 1. Validate the directive has completed step tasks
/// 2. Create the completion task (so we have a real task ID)
/// 3. Atomically claim the directive for completion with the real task ID
/// 4. Dispatch the task to a daemon
///
/// Returns the created task ID on success.
pub async fn trigger_completion_task(
    pool: &PgPool,
    state: &SharedState,
    directive_id: Uuid,
    owner_id: Uuid,
) -> Result<Uuid, anyhow::Error> {
    let directive = repository::get_directive_for_owner(pool, owner_id, directive_id)
        .await?
        .ok_or_else(|| anyhow::anyhow!("Directive not found"))?;

    // Check for already-running completion task
    if directive.completion_task_id.is_some() {
        anyhow::bail!("A completion task is already running for this directive");
    }

    let step_tasks = repository::get_completed_step_tasks(pool, directive_id).await?;
    if step_tasks.is_empty() {
        anyhow::bail!("No completed steps with tasks found");
    }

    let base_branch = directive.base_branch.as_deref().unwrap_or("main");

    let directive_branch = format!(
        "makima/directive-{}-{}",
        crate::daemon::worktree::sanitize_name(&directive.title),
        crate::daemon::worktree::short_uuid(directive.id),
    );

    let step_branches: Vec<String> = step_tasks
        .iter()
        .map(|st| {
            format!(
                "makima/{}-{}",
                crate::daemon::worktree::sanitize_name(&st.task_name),
                crate::daemon::worktree::short_uuid(st.task_id),
            )
        })
        .collect();

    let prompt = build_completion_prompt(&directive, &step_tasks, &step_branches, &directive_branch, base_branch);

    let task_name = if directive.pr_url.is_some() {
        format!("Update PR: {}", directive.title)
    } else {
        format!("PR: {}", directive.title)
    };

    // Create the completion task FIRST so we have a real task ID for the FK
    let req = CreateTaskRequest {
        contract_id: None,
        name: task_name,
        description: Some("Directive PR completion task".to_string()),
        plan: prompt,
        parent_task_id: None,
        is_supervisor: false,
        priority: 0,
        repository_url: directive.repository_url.clone(),
        base_branch: directive.base_branch.clone(),
        target_branch: None,
        merge_mode: None,
        target_repo_path: None,
        completion_action: None,
        continue_from_task_id: None,
        copy_files: None,
        checkpoint_sha: None,
        branched_from_task_id: None,
        conversation_history: None,
        supervisor_worktree_task_id: None,
        directive_id: Some(directive_id),
        directive_step_id: None,
    };

    let task = repository::create_task_for_owner(pool, owner_id, req).await?;

    // Atomically claim the directive with the REAL task ID (satisfies FK constraint).
    // This prevents concurrent ticks from also spawning a completion task.
    let claimed =
        repository::claim_directive_for_completion(pool, directive_id, task.id).await?;
    if !claimed {
        anyhow::bail!("Directive already claimed for completion");
    }

    // Update pr_branch on the directive
    let update = crate::db::models::UpdateDirectiveRequest {
        pr_branch: Some(directive_branch),
        ..Default::default()
    };
    let _ = repository::update_directive_for_owner(pool, owner_id, directive_id, update).await;

    // Try to dispatch to a daemon
    if let Some(daemon_id) = state.find_alternative_daemon(owner_id, &[]) {
        let update_req = crate::db::models::UpdateTaskRequest {
            status: Some("starting".to_string()),
            daemon_id: Some(daemon_id),
            version: Some(task.version),
            ..Default::default()
        };

        if let Ok(Some(updated_task)) =
            repository::update_task_for_owner(pool, task.id, owner_id, update_req).await
        {
            let (patch_data, patch_base_sha) =
                if let Some(from_id) = updated_task.continue_from_task_id {
                    match repository::get_latest_checkpoint_patch(pool, from_id).await {
                        Ok(Some(patch)) => {
                            let encoded = base64::engine::general_purpose::STANDARD
                                .encode(&patch.patch_data);
                            (Some(encoded), Some(patch.base_commit_sha))
                        }
                        _ => (None, None),
                    }
                } else {
                    (None, None)
                };

            let command = DaemonCommand::SpawnTask {
                task_id: task.id,
                task_name: task.name.clone(),
                plan: task.plan.clone(),
                repo_url: updated_task.repository_url.clone(),
                base_branch: updated_task.base_branch.clone(),
                target_branch: updated_task.target_branch.clone(),
                parent_task_id: None,
                depth: 0,
                is_orchestrator: false,
                target_repo_path: None,
                completion_action: updated_task.completion_action.clone(),
                continue_from_task_id: updated_task.continue_from_task_id,
                copy_files: None,
                contract_id: None,
                is_supervisor: false,
                autonomous_loop: false,
                resume_session: false,
                conversation_history: None,
                patch_data,
                patch_base_sha,
                local_only: false,
                auto_merge_local: false,
                supervisor_worktree_task_id: None,
                directive_id: updated_task.directive_id,
            };

            if let Err(e) = state.send_daemon_command(daemon_id, command).await {
                tracing::warn!(
                    task_id = %task.id,
                    daemon_id = %daemon_id,
                    error = %e,
                    "Failed to dispatch completion task to daemon"
                );
            }
        }
    }

    Ok(task.id)
}

/// Build the planning prompt for a directive.
fn build_planning_prompt(
    directive: &crate::db::models::Directive,
    existing_steps: &[crate::db::models::DirectiveStep],
    generation: i32,
    goal_history: &[crate::db::models::DirectiveGoalHistory],
) -> String {
    let mut prompt = String::new();

    if !existing_steps.is_empty() {
        // ── RE-PLANNING header ──────────────────────────────────────
        prompt.push_str(&format!(
            "⚠️  RE-PLANNING: The GOAL has been updated — you must re-evaluate ALL existing steps.\n\
             Previous steps were planned for an earlier version of the goal. Some may no longer be \
             relevant. Review each step below and act according to the instructions per status category.\n\n",
        ));

        // ── Goal changes section ──────────────────────────────────
        if !goal_history.is_empty() {
            prompt.push_str("-- GOAL CHANGES --\n");
            prompt.push_str("The goal has been updated. Compare the previous and current goals to understand what changed:\n\n");
            for (i, entry) in goal_history.iter().enumerate() {
                if i == 0 {
                    prompt.push_str(&format!(
                        "PREVIOUS GOAL (replaced at {}):\n{}\n\n",
                        entry.created_at.format("%Y-%m-%d %H:%M:%S UTC"),
                        entry.goal
                    ));
                } else {
                    prompt.push_str(&format!(
                        "OLDER GOAL (version from {}):\n{}\n\n",
                        entry.created_at.format("%Y-%m-%d %H:%M:%S UTC"),
                        entry.goal
                    ));
                }
            }
            prompt.push_str(&format!(
                "CURRENT GOAL (what you must plan for):\n{}\n\n",
                directive.goal
            ));
            prompt.push_str(
                "IMPORTANT: Analyze what CHANGED between the previous goal and the current goal.\n\
                 - If the change is minor (e.g., clarification, small addition), try to KEEP existing pending steps and only add/modify what is needed for the delta.\n\
                 - If the change is major (e.g., completely different objective), you may need to remove most pending steps and create a fresh plan.\n\
                 - Always preserve completed and running steps - they represent work already done.\n\n",
            );
        }

        prompt.push_str(&format!(
            "EXISTING STEPS (generation {}):\n",
            generation - 1
        ));

        // Categorise steps by status
        let mut completed: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut running: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut pending_ready: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut failed: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut skipped: Vec<&crate::db::models::DirectiveStep> = Vec::new();

        for step in existing_steps {
            match step.status.as_str() {
                "completed" => completed.push(step),
                "running" => running.push(step),
                "pending" | "ready" => pending_ready.push(step),
                "failed" => failed.push(step),
                "skipped" => skipped.push(step),
                _ => pending_ready.push(step),
            }
        }

        // ── Completed steps ─────────────────────────────────────────
        if !completed.is_empty() {
            prompt.push_str("\n── COMPLETED steps (KEEP — work already done) ──\n");
            prompt.push_str("These steps have finished. Their work is committed and available.\n");
            prompt.push_str("Do NOT remove them. New steps can depend on them to inherit their changes.\n");
            let mut last_completed_id: Option<Uuid> = None;
            for step in &completed {
                prompt.push_str(&format!(
                    "  ✅ {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
                last_completed_id = Some(step.id);
            }
            if let Some(last_id) = last_completed_id {
                prompt.push_str(&format!(
                    "\nNew steps that build on previous work SHOULD use --depends-on \"{}\" (the last completed step) \
                     so their worktree inherits all prior changes. Without this dependency, new steps start from a \
                     fresh checkout and won't see any of the work done by previous steps.\n",
                    last_id
                ));
            }
        }

        // ── Running steps ───────────────────────────────────────────
        if !running.is_empty() {
            prompt.push_str("\n── RUNNING steps (cannot remove — note if obsolete) ──\n");
            prompt.push_str("These steps are currently executing and cannot be removed or skipped.\n");
            prompt.push_str("If a running step is no longer relevant to the NEW goal, note it but do not attempt to remove it.\n");
            for step in &running {
                prompt.push_str(&format!(
                    "  🔄 {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        // ── Pending / Ready steps ───────────────────────────────────
        if !pending_ready.is_empty() {
            prompt.push_str("\n── PENDING/READY steps (EVALUATE — remove if no longer relevant) ──\n");
            prompt.push_str("These steps have NOT started yet. Evaluate each against the NEW goal:\n");
            prompt.push_str("  • If still relevant → leave it in place (no action needed).\n");
            prompt.push_str("  • If NO LONGER relevant → remove it with: makima directive remove-step <step_id>\n");
            for step in &pending_ready {
                prompt.push_str(&format!(
                    "  ⏳ [{}] {} (id: {}): {}\n",
                    step.status,
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        // ── Failed steps ────────────────────────────────────────────
        if !failed.is_empty() {
            prompt.push_str("\n── FAILED steps (EVALUATE — remove if no longer relevant) ──\n");
            prompt.push_str("These steps failed. Evaluate each against the NEW goal:\n");
            prompt.push_str("  • If still relevant → remove the failed step and re-add a corrected version.\n");
            prompt.push_str("  • If NO LONGER relevant → remove it with: makima directive remove-step <step_id>\n");
            for step in &failed {
                prompt.push_str(&format!(
                    "  ❌ {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        // ── Skipped steps ───────────────────────────────────────────
        if !skipped.is_empty() {
            prompt.push_str("\n── SKIPPED steps (remove if no longer relevant) ──\n");
            for step in &skipped {
                prompt.push_str(&format!(
                    "  ⏭️  {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        // ── Instructions ────────────────────────────────────────────
        prompt.push_str(&format!(
            "\n── ACTION PLAN ──\n\
             1. First, remove any pending/ready/failed/skipped steps that are NOT relevant to the NEW goal:\n\
             \x20  makima directive remove-step <step_id>\n\
             2. Then, add new steps for the updated goal. Use generation {}.\n\
             3. New steps that build on completed work MUST use --depends-on to inherit the worktree.\n\
             4. Ensure the new plan fully addresses the UPDATED goal.\n\
             5. If the updated goal is unclear or ambiguous, ask the user for clarification using:\n\
             \x20  makima directive ask \"<question>\" --phaseguard\n\n",
            generation
        ));
    }

    prompt.push_str(&format!(
        r#"You are planning the implementation of a directive.

DIRECTIVE: "{title}"
GOAL: {goal}
{repo_section}
Your job:
1. Explore the repository to understand the codebase
2. Decompose the goal into concrete, ordered steps
3. Each step = one task for a Claude Code instance to execute
4. Submit ALL steps using the batch command or individual add-step commands

For each step, define:
- name: Short imperative title (e.g., "Add user authentication middleware")
- description: What to do and acceptance criteria
- taskPlan: Full instructions for the Claude instance (include file paths, patterns to follow)
- dependsOn: UUIDs of steps this depends on (use IDs from previous add-step responses)
- orderIndex: Execution phase number. Steps only start after ALL steps with a lower orderIndex complete.
  Steps with the same orderIndex run in parallel. Use ascending values (0, 1, 2, ...) to create sequential phases.
  Use dependsOn for fine-grained control within the same phase.
- contractType (OPTIONAL): For large, complex work items, set this to create a full contract instead of a
  standalone task. Valid values: "simple" (Plan → Execute), "specification" (Research → Specify → Plan → Execute → Review),
  "execute" (Execute only). Only use this for steps that truly need multi-phase orchestration.
  Most steps should NOT use this — standalone tasks are the default and preferred for typical work.

Submit steps:
  makima directive add-step "Step Name" --description "..." --task-plan "..."
  (Use --depends-on "uuid1,uuid2" for dependencies, referencing IDs from earlier add-step outputs)

Or batch:
  makima directive batch-add-steps --json '[{{"name":"...","description":"...","taskPlan":"...","dependsOn":[],"orderIndex":0}}]'

DEPENDENCY WORKTREE CONTINUATION:
Each step runs in its own git worktree. How that worktree is initialised depends on dependsOn:
- With dependsOn: the step continues from the first dependency's worktree (inheriting all committed and
  uncommitted changes). Additional dependencies are merged in as branches before work starts.
- Without dependsOn: the step starts from a FRESH worktree based on the base branch (or the PR branch if
  a PR already exists from previous completions).

Because of this, you MUST chain steps using dependsOn whenever one step's work builds on another's.
If step B modifies files created/changed by step A, step B MUST list step A in its dependsOn — otherwise
step B will start from a blank worktree and won't see step A's changes at all.

Guidelines:
- For sequential work, create a linear chain: step1 → step2 → step3 (each depends on the previous).
- Only omit dependsOn for truly independent steps that can start from a fresh checkout.
- Parallel steps that share no files can omit mutual dependencies, but if they both build on a prior step
  they should BOTH list that prior step in dependsOn.

IMPORTANT: Each step's taskPlan must be self-contained. The executing instance won't have your planning context.

ASKING QUESTIONS:
If you need clarification from the user before finalizing the plan, you can ask questions:
  makima directive ask "Your question here"
  makima directive ask "Which approach?" --choices "Option A,Option B" --phaseguard
  makima directive ask "Confirm this approach?" --context "Additional context here" --phaseguard

Use --phaseguard for questions that block progress (the question will wait indefinitely for a response).
The CLI automatically reconnects via polling every ~5 minutes to avoid HTTP timeout limits.
Without --phaseguard, questions timeout based on the directive's reconcile mode:
- Auto: questions timeout after 30 seconds with no response
- Semi-Auto: questions wait indefinitely (with automatic reconnecting polls every ~5 min)
- Manual: questions wait indefinitely + tasks should ask multiple clarifying questions

When to ask:
- Requirements are ambiguous and multiple interpretations are valid
- There are multiple equally valid technical approaches
- You need domain-specific knowledge that cannot be inferred from the codebase
- A decision has significant downstream impact and user preference matters

Do NOT ask questions for:
- Implementation details you can determine from the codebase
- Standard engineering decisions with clear best practices
- Trivial choices that do not significantly affect the outcome

CREATING ORDERS FOR FUTURE WORK:
If you discover work that is out of scope for the current plan but should be tracked, create an order:
  makima directive create-order --title "Order title" --order-type spike
  makima directive create-order --title "Fix flaky test" --order-type chore --priority high --description "Details..."

Only spike and chore types are allowed. The order is automatically linked to this directive.

When to create orders:
- You discover follow-up work that is outside the current goal
- A spike reveals additional tasks that need future attention
- You identify technical debt or maintenance chores during planning
- Something needs investigation but is not blocking the current plan

Do NOT create orders for:
- Work that should be a step in the current plan
- Tasks that are part of the current goal
"#,
        title = directive.title,
        goal = directive.goal,
        repo_section = match &directive.repository_url {
            Some(url) => format!("REPOSITORY: {}\n", url),
            None => String::new(),
        },
    ));

    prompt
}

/// Build the prompt for a completion task that creates or updates a PR.
fn build_completion_prompt(
    directive: &crate::db::models::Directive,
    step_tasks: &[crate::db::repository::CompletedStepTask],
    step_branches: &[String],
    directive_branch: &str,
    base_branch: &str,
) -> String {
    let merge_commands: String = step_branches
        .iter()
        .map(|b| format!("git merge origin/{} --no-edit", b))
        .collect::<Vec<_>>()
        .join("\n");

    let step_summary: String = step_tasks
        .iter()
        .zip(step_branches.iter())
        .map(|(st, branch)| format!("- {} (branch: {})", st.step_name, branch))
        .collect::<Vec<_>>()
        .join("\n");

    if let Some(ref pr_url) = directive.pr_url {
        // Re-completion: PR already exists — but it may have been merged or closed.
        // We must check the PR state first and handle accordingly.
        format!(
            r#"You are updating an existing PR for directive "{title}".

IMPORTANT: The previous PR may have been merged or closed. You MUST check its state first.

## Step 1: Check PR state

Run this command to check the PR state:
```
gh pr view {pr_url} --json state --jq '.state'
```

## If the PR state is MERGED or CLOSED:

The previous PR was already merged/closed. You need to create a NEW PR with a fresh branch.

Goal: {goal}

Steps completed:
{step_summary}

1. Clear the old PR URL:
```
makima directive update --pr-url ""
```

2. Create a fresh branch with a timestamp suffix to avoid collision:
```
git fetch origin
NEW_BRANCH="{directive_branch}-v$(date +%s)"
git checkout -b "$NEW_BRANCH" origin/{base_branch}
{merge_commands}
git push -u origin "$NEW_BRANCH"
```

For each step branch merge above, if a merge fails with conflicts:
1. First try: `git merge --abort` then retry with `git merge <the-failing-branch> -X theirs --no-edit`
2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
3. Continue with remaining merges

3. Generate a descriptive PR title and create a new PR:

Based on the steps completed above, generate a descriptive PR title that summarizes the actual changes (not just the directive name "{title}"). The title should:
- Be concise (under 72 characters)
- Describe WHAT was done, not just the project name
- Use conventional commit style if appropriate (feat:, fix:, refactor:, etc.)

Then create the PR:
```
gh pr create --title "<YOUR_GENERATED_TITLE>" --body "{pr_body}" --head "$NEW_BRANCH" --base {base_branch}
```
Replace <YOUR_GENERATED_TITLE> with the concise descriptive title you generated.

4. Store the new PR URL:
```
makima directive update --pr-url "<URL_FROM_GH_PR_CREATE>"
```
Replace the URL with the actual PR URL from the `gh pr create` output. This step is CRITICAL.

5. Update the directive pr_branch to the new branch name:
```
makima directive update --pr-branch "$NEW_BRANCH"
```

## If the PR state is OPEN:

The PR is still open. Merge new step branches into the existing PR branch.

Steps completed:
{step_summary}

Run these commands:
```
git fetch origin
git checkout {directive_branch}
git pull origin {directive_branch}
git merge origin/{base_branch} --no-edit
{merge_commands}
git push origin {directive_branch}
```

Already-merged branches will be a no-op. If a merge fails with conflicts:
1. First try: `git merge --abort` then retry with `git merge <the-failing-branch> -X theirs --no-edit`
2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
3. Continue with remaining merges

If you encounter issues you cannot resolve (e.g., persistent merge conflicts, PR update failures), you can ask for help:
  makima directive ask "Your question" --phaseguard
"#,
            title = directive.title,
            goal = directive.goal,
            pr_url = pr_url,
            directive_branch = directive_branch,
            base_branch = base_branch,
            step_summary = step_summary,
            merge_commands = merge_commands,
            pr_body = format!(
                "## Directive\\n\\n{}\\n\\n## Steps\\n\\n{}",
                directive.goal.replace('\n', "\\n").replace('"', "\\\""),
                step_summary.replace('\n', "\\n").replace('"', "\\\""),
            ),
        )
    } else {
        // First completion: create new PR
        format!(
            r#"You are creating a PR for directive "{title}".

Goal: {goal}

Steps completed:
{step_summary}

Run these commands to create a combined branch and PR:
```
git fetch origin
git checkout -b {directive_branch} origin/{base_branch}
{merge_commands}
git push -u origin {directive_branch}
```

Then generate a descriptive PR title and create the PR:

Based on the steps completed above, generate a descriptive PR title that summarizes the actual changes (not just the directive name "{title}"). The title should:
- Be concise (under 72 characters)
- Describe WHAT was done, not just the project name
- Use conventional commit style if appropriate (feat:, fix:, refactor:, etc.)
For example, instead of "soryu-co/soryu - makima" use something like "Fix order lifecycle, PR update, and contracts overflow".

```
gh pr create --title "<YOUR_GENERATED_TITLE>" --body "{pr_body}" --head {directive_branch} --base {base_branch}
```
Replace <YOUR_GENERATED_TITLE> with the concise descriptive title you generated.

IMPORTANT: After creating the PR, you MUST store the PR URL so the directive system can track it.

1. Run `gh pr create` as shown above and capture its output
2. The output will contain the PR URL (e.g., https://github.com/owner/repo/pull/123)
3. Then run this command to store the URL:
```
makima directive update --pr-url "https://github.com/..."
```
Replace the URL with the actual PR URL from the `gh pr create` output. This step is CRITICAL — the PR will not be tracked by the directive system without it.

For each step branch merge, if a merge fails with conflicts:
1. First try: `git merge --abort` then retry with `git merge <the-failing-branch> -X theirs --no-edit`
2. If that also fails, manually resolve the conflicts, `git add .`, and `git commit --no-edit`
3. Continue with remaining merges

If you encounter issues you cannot resolve (e.g., persistent merge conflicts, PR creation failures), you can ask for help:
  makima directive ask "Your question" --phaseguard
"#,
            title = directive.title,
            goal = directive.goal,
            directive_branch = directive_branch,
            base_branch = base_branch,
            step_summary = step_summary,
            merge_commands = merge_commands,
            pr_body = format!(
                "## Directive\\n\\n{}\\n\\n## Steps\\n\\n{}",
                directive.goal.replace('\n', "\\n").replace('"', "\\\""),
                step_summary.replace('\n', "\\n").replace('"', "\\\""),
            ),
        )
    }
}

/// Build a prompt for verifying whether a PR was created for a directive.
/// This is a one-shot task: if it can't find or create the PR, the directive
/// will be marked completed to avoid infinite retries.
fn build_verification_prompt(
    directive: &crate::db::models::Directive,
    pr_branch: &str,
    base_branch: &str,
) -> String {
    format!(
        r#"You are verifying whether a PR exists for directive "{title}".

The completion task already ran and pushed branch `{pr_branch}`, but the PR URL was not captured.

Follow these steps IN ORDER:

1. Check if a PR already exists for this branch:
```
gh pr list --head {pr_branch} --json url --jq '.[0].url'
```

2. If the command outputs a URL, store it:
```
makima directive update --pr-url "<URL_FROM_ABOVE>"
```
Done — the PR already exists.

3. If no PR was found, check if the branch exists on the remote:
```
git ls-remote --heads origin {pr_branch}
```

4. If the branch exists, generate a descriptive PR title and create the PR:

Based on the branch name and directive "{title}", generate a descriptive PR title that summarizes the actual changes. The title should:
- Be concise (under 72 characters)
- Describe WHAT was done, not just the project name
- Use conventional commit style if appropriate (feat:, fix:, refactor:, etc.)

```
gh pr create --title "<YOUR_GENERATED_TITLE>" --body "Directive PR verification — auto-created" --head {pr_branch} --base {base_branch}
```
Then store the resulting URL:
```
makima directive update --pr-url "<URL_FROM_GH_PR_CREATE>"
```

5. If the branch does NOT exist on the remote, the work was likely merged directly.
Mark the directive as completed:
```
makima directive update --status archived
```

IMPORTANT: You MUST run `makima directive update` with either `--pr-url` or `--status archived` before finishing.
"#,
        title = directive.title,
        pr_branch = pr_branch,
        base_branch = base_branch,
    )
}

/// Build a prompt for cleaning up completed steps that have been merged into the PR branch.
///
/// The prompt instructs the Claude instance to verify which step branches are
/// merged and remove merged steps, leaving unmerged steps alone.
pub fn build_cleanup_prompt(
    directive: &crate::db::models::Directive,
    step_tasks: &[crate::db::repository::CompletedStepTask],
    pr_branch: &str,
    base_branch: &str,
) -> String {
    let step_list: String = step_tasks
        .iter()
        .map(|st| {
            let branch = format!(
                "makima/{}-{}",
                crate::daemon::worktree::sanitize_name(&st.task_name),
                crate::daemon::worktree::short_uuid(st.task_id),
            );
            format!("- Step ID: {}, Name: \"{}\", Branch: {}", st.step_id, st.step_name, branch)
        })
        .collect::<Vec<_>>()
        .join("\n");

    let pr_url_line = match &directive.pr_url {
        Some(url) => format!("PR URL: {}", url),
        None => String::new(),
    };

    format!(
        r#"You are cleaning up completed steps for directive "{title}".

The directive has a PR branch: {pr_branch}
Base branch: {base_branch}
{pr_url_line}

Completed steps to verify:
{step_list}

## Instructions

1. First, fetch the latest remote state:
```bash
git fetch origin
```

2. Check which branches have been merged into the PR branch:
```bash
git branch -r --merged origin/{pr_branch}
```

3. For each completed step listed above, check if its branch appears in the merged list.

4. For steps whose branches ARE merged:
   - Remove the step (this also cleans up associated data):
```bash
makima directive remove-step <step_id>
```

5. For steps whose branches are NOT merged into the PR branch:
   - Do NOT remove them. Leave them for the next PR cycle.
   - Report them as skipped.

6. After processing all steps, report a summary of what was cleaned up and what was left.

IMPORTANT: Only remove steps whose task branches have been verified as merged. Never remove unmerged steps.

If you encounter issues you cannot resolve during cleanup, you can ask for help:
  makima directive ask "Your question" --phaseguard"#,
        title = directive.title,
        pr_branch = pr_branch,
        base_branch = base_branch,
        pr_url_line = pr_url_line,
        step_list = step_list,
    )
}

/// Build a specialized planning prompt for picking up open orders.
///
/// This prompt instructs the planner to evaluate available orders, select an
/// adequate number based on priority and directive capacity, and create steps
/// to fulfil them.
pub fn build_order_pickup_prompt(
    directive: &crate::db::models::Directive,
    existing_steps: &[crate::db::models::DirectiveStep],
    orders: &[crate::db::models::Order],
    generation: i32,
    goal_history: &[crate::db::models::DirectiveGoalHistory],
) -> String {
    let mut prompt = String::new();

    // ── Directive context ──────────────────────────────────────────
    prompt.push_str(&format!(
        "You are planning work for directive \"{title}\".\n\n\
         GOAL: {goal}\n\
         {repo_section}\n",
        title = directive.title,
        goal = directive.goal,
        repo_section = match &directive.repository_url {
            Some(url) => format!("REPOSITORY: {}\n", url),
            None => String::new(),
        },
    ));

    // ── Goal history (if any) ─────────────────────────────────────
    if !goal_history.is_empty() {
        prompt.push_str("-- GOAL CHANGES --\n");
        for (i, entry) in goal_history.iter().enumerate() {
            if i == 0 {
                prompt.push_str(&format!(
                    "PREVIOUS GOAL (replaced at {}):\n{}\n\n",
                    entry.created_at.format("%Y-%m-%d %H:%M:%S UTC"),
                    entry.goal
                ));
            } else {
                prompt.push_str(&format!(
                    "OLDER GOAL (version from {}):\n{}\n\n",
                    entry.created_at.format("%Y-%m-%d %H:%M:%S UTC"),
                    entry.goal
                ));
            }
        }
    }

    // ── Orders being picked up ───────────────────────────────────
    prompt.push_str("== ORDERS AVAILABLE FOR PLANNING ==\n");
    prompt.push_str("The following open orders have been linked to this directive. \
                     Review them and create steps to fulfil them.\n\n");
    for (i, order) in orders.iter().enumerate() {
        prompt.push_str(&format!(
            "  {}. [{}] [{}] {}\n     orderId: {}\n",
            i + 1,
            order.priority,
            order.order_type,
            order.title,
            order.id,
        ));
        if let Some(ref desc) = order.description {
            prompt.push_str(&format!("     Description: {}\n", desc));
        }
    }
    prompt.push('\n');

    // ── Existing steps ───────────────────────────────────────────
    if !existing_steps.is_empty() {
        let mut completed: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut running: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut pending_ready: Vec<&crate::db::models::DirectiveStep> = Vec::new();
        let mut failed: Vec<&crate::db::models::DirectiveStep> = Vec::new();

        for step in existing_steps {
            match step.status.as_str() {
                "completed" => completed.push(step),
                "running" => running.push(step),
                "pending" | "ready" => pending_ready.push(step),
                "failed" => failed.push(step),
                _ => pending_ready.push(step),
            }
        }

        prompt.push_str("== EXISTING STEPS ==\n");

        if !completed.is_empty() {
            prompt.push_str("\n── COMPLETED steps (work already done) ──\n");
            let mut last_completed_id: Option<uuid::Uuid> = None;
            for step in &completed {
                prompt.push_str(&format!(
                    "  ✅ {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
                last_completed_id = Some(step.id);
            }
            if let Some(last_id) = last_completed_id {
                prompt.push_str(&format!(
                    "\nNew steps that build on previous work SHOULD use --depends-on \"{}\" \
                     so their worktree inherits all prior changes.\n",
                    last_id
                ));
            }
        }

        if !running.is_empty() {
            prompt.push_str("\n── RUNNING steps (in progress) ──\n");
            for step in &running {
                prompt.push_str(&format!(
                    "  🔄 {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        if !pending_ready.is_empty() {
            prompt.push_str("\n── PENDING/READY steps (not yet started) ──\n");
            for step in &pending_ready {
                prompt.push_str(&format!(
                    "  ⏳ [{}] {} (id: {}): {}\n",
                    step.status,
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        if !failed.is_empty() {
            prompt.push_str("\n── FAILED steps ──\n");
            for step in &failed {
                prompt.push_str(&format!(
                    "  ❌ {} (id: {}): {}\n",
                    step.name,
                    step.id,
                    step.description.as_deref().unwrap_or("(no description)")
                ));
            }
        }

        // Determine whether to create fresh steps or combine with existing
        let all_terminal = existing_steps
            .iter()
            .all(|s| matches!(s.status.as_str(), "completed" | "failed" | "skipped"));

        if all_terminal {
            prompt.push_str(
                "\nAll existing steps are in terminal state (completed/failed/skipped). \
                 Create FRESH steps from the orders above.\n\n",
            );
        } else if !pending_ready.is_empty() || !running.is_empty() {
            prompt.push_str(
                "\nThere are existing active/pending steps. Evaluate whether to KEEP them \
                 and ADD new steps from the orders, creating a combined plan. \
                 Do not duplicate work already covered by existing steps.\n\n",
            );
        }
    }

    // ── Order selection guidance ─────────────────────────────────
    prompt.push_str(&format!(
        "== ORDER SELECTION GUIDANCE ==\n\
         You do NOT need to pick up ALL orders. Select an ADEQUATE number based on:\n\
         - Priority: prefer critical and high priority orders first\n\
         - Directive scope: consider the directive's current goal and capacity\n\
         - Avoid overloading: don't assign too many orders to a single directive\n\
         - The orders are already linked to this directive — focus on creating steps\n\n\
         If some orders are not relevant to this directive's goal or would overload it, \
         you may leave them for a future pickup cycle.\n\n"
    ));

    // ── Step creation instructions ───────────────────────────────
    prompt.push_str(&format!(
        r#"== STEP CREATION INSTRUCTIONS ==
For each order (or group of related orders), create one or more steps:
- name: Short imperative title (e.g., "Add user authentication middleware")
- description: What to do and acceptance criteria
- taskPlan: Full instructions for the Claude instance (include file paths, patterns to follow)
- dependsOn: UUIDs of steps this depends on (use IDs from previous add-step responses)
- orderIndex: Execution phase number. Steps only start after ALL steps with a lower orderIndex complete.
  Steps with the same orderIndex run in parallel. Use ascending values (0, 1, 2, ...) to create sequential phases.
- orderId: The UUID of the order this step fulfils. Include this so the order is automatically marked done
  when the step completes. Use the orderId shown in the order listing above.

Submit steps using generation {generation}:
  makima directive add-step "Step Name" --description "..." --task-plan "..." --generation {generation}
  (Use --depends-on "uuid1,uuid2" for dependencies)

Or batch:
  makima directive batch-add-steps --json '[{{"name":"...","description":"...","taskPlan":"...","dependsOn":[],"orderIndex":0,"generation":{generation},"orderId":"<order-uuid>"}}]'

DEPENDENCY WORKTREE CONTINUATION:
Each step runs in its own git worktree. How that worktree is initialised depends on dependsOn:
- With dependsOn: the step continues from the first dependency's worktree (inheriting all committed and
  uncommitted changes). Additional dependencies are merged in as branches before work starts.
- Without dependsOn: the step starts from a FRESH worktree based on the base branch (or the PR branch if
  a PR already exists from previous completions).

Because of this, you MUST chain steps using dependsOn whenever one step's work builds on another's.
If step B modifies files created/changed by step A, step B MUST list step A in its dependsOn — otherwise
step B will start from a blank worktree and won't see step A's changes at all.

Guidelines:
- For sequential work, create a linear chain: step1 → step2 → step3 (each depends on the previous).
- Only omit dependsOn for truly independent steps that can start from a fresh checkout.
- Parallel steps that share no files can omit mutual dependencies, but if they both build on a prior step
  they should BOTH list that prior step in dependsOn.

IMPORTANT: Each step's taskPlan must be self-contained. The executing instance won't have your planning context.

## Asking Questions

If you need clarification about the goal, requirements, or implementation approach, you can ask the user:
```bash
makima directive ask "Your question here"
```

Options:
- `--choices "opt1,opt2,opt3"` - Provide choices
- `--context "<context>"` - Additional context
- `--phaseguard` - Block until response (recommended for important questions)

The question will appear in the directive UI. Behavior depends on reconcile mode:
- Auto: times out after 30s (use for non-critical questions)
- Semi-Auto: blocks until user responds
- Manual: blocks until user responds (tasks are expected to ask many questions)

Use this when:
- The goal is ambiguous and could be interpreted multiple ways
- You need to choose between significantly different implementation approaches
- You discover constraints that affect the plan

Do NOT ask questions for trivial decisions — use your best judgment.
"#,
        generation = generation,
    ));

    prompt
}