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,
    /// Last time we ran the tmp-task expiry sweep. Throttled to once an
    /// hour so the deletion query doesn't run on every 15-second tick.
    last_tmp_sweep: std::time::Instant,
}

impl DirectiveOrchestrator {
    pub fn new(pool: PgPool, state: SharedState) -> Self {
        Self {
            pool,
            state,
            // Initialise to 1 hour ago so the first tick after startup runs
            // the sweep immediately — clears any tasks that aged out while
            // the server was down.
            last_tmp_sweep: std::time::Instant::now()
                - std::time::Duration::from_secs(3600),
        }
    }

    /// 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");
        }
        // Throttled to hourly — the actual delete is cheap (indexed
        // partial scan) but we don't want to log a sweep every 15s.
        if self.last_tmp_sweep.elapsed() >= std::time::Duration::from_secs(3600) {
            self.last_tmp_sweep = std::time::Instant::now();
            if let Err(e) = self.phase_tmp_expiry().await {
                tracing::warn!(error = %e, "Directive phase_tmp_expiry 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"
            );

            // If the contract has previously-merged revisions, this is an
            // amendment — pass the latest merged revision so the planner can
            // reason about the delta instead of replanning from scratch.
            let prev_merged = repository::get_latest_merged_revision(&self.pool, directive.id)
                .await
                .unwrap_or(None);
            let contract_body =
                repository::get_active_contract_body(&self.pool, directive.id).await?;

            let plan = build_planning_prompt(
                &directive,
                &[],
                1,
                &contract_body,
                None,
                prev_merged.as_ref(),
            );

            if let Err(e) = self
                .spawn_orchestrator_task(
                    directive.id,
                    directive.owner_id,
                    "orchestrator".to_string(),
                    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 {
            // contract_type used to spawn a heavyweight contract+supervisor
            // for a step. The contracts subsystem has been removed (Phase 5);
            // we now treat any contract-backed step as a plain standalone
            // task. The column itself is left in place for one more release
            // so old data still reads cleanly, but it has no effect.
            if step.contract_type.is_some() {
                tracing::warn!(
                    step_id = %step.step_id,
                    directive_id = %step.directive_id,
                    contract_type = ?step.contract_type,
                    "Step has legacy contract_type; falling back to standalone task spawn"
                );
            }

            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 {
            if let Err(e) = async {
                tracing::info!(
                    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 contract_body =
                    repository::get_active_contract_body(&self.pool, directive.id).await?;

                // If steps are currently running (or recently completed), build a
                // WORK IN PROGRESS summary for the planner so it doesn't re-issue
                // already-running work. We only include this section when there
                // really is work in flight — pure pending plans don't need it.
                let progress_summary =
                    summarize_in_progress_steps(&existing_steps);

                // If the contract has previously-merged revisions, this is an
                // amendment — pass the latest merged revision so the planner
                // sees the BEFORE→AFTER diff for the new PR.
                let prev_merged = repository::get_latest_merged_revision(&self.pool, directive.id)
                    .await
                    .unwrap_or(None);

                let plan = build_planning_prompt(
                    &directive,
                    &existing_steps,
                    generation,
                    &contract_body,
                    progress_summary.as_deref(),
                    prev_merged.as_ref(),
                );

                if let Err(e) = self
                    .spawn_orchestrator_task(
                        directive.id,
                        directive.owner_id,
                        "orchestrator (re-plan)".to_string(),
                        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_step_contract was removed in Phase 5 — the contracts subsystem
    // is gone. Step rows with `contract_type` set are now silently treated
    // as standalone tasks (see the warn! in phase_execution).

    /// 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
    }

    /// Hourly sweep — delete top-level tasks attached to any tmp directive
    /// that are older than 30 days. Per-owner; no global cap. Subtasks die
    /// via the FK cascade.
    async fn phase_tmp_expiry(&self) -> Result<(), anyhow::Error> {
        let tmps = repository::list_all_tmp_directives(&self.pool).await?;
        let mut total_deleted: u64 = 0;
        for d in tmps {
            match repository::delete_expired_tmp_tasks(&self.pool, d.id).await {
                Ok(n) => {
                    if n > 0 {
                        tracing::info!(
                            directive_id = %d.id,
                            owner_id = %d.owner_id,
                            deleted = n,
                            "Expired tmp tasks deleted (>30 days old)"
                        );
                        total_deleted += n;
                    }
                }
                Err(e) => {
                    tracing::warn!(
                        directive_id = %d.id,
                        error = %e,
                        "Failed to expire tmp tasks for owner"
                    );
                }
            }
        }
        if total_deleted > 0 {
            tracing::info!(total = total_deleted, "Tmp expiry sweep completed");
        }
        Ok(())
    }

    /// 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 contract_body = repository::get_active_contract_body(&self.pool, directive.id)
                    .await
                    .unwrap_or_default();
                let prompt = build_completion_prompt(
                    &directive,
                    &contract_body,
                    &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,
                        "completion".to_string(),
                        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.clone()),
                                        ..Default::default()
                                    };
                                    let _ = repository::update_directive_for_owner(
                                        &self.pool,
                                        check.owner_id,
                                        check.directive_id,
                                        update,
                                    )
                                    .await;

                                    // Lifecycle hook: mark the currently-active directive
                                    // document as shipped (records pr_url + pr_branch and
                                    // flips status to 'shipped'), then auto-create a fresh
                                    // empty draft document under the same directive so the
                                    // user has a clean slate for the next batch of work.
                                    //
                                    // Per the goal: "automatically create a new empty draft
                                    // contract" once the previous contract ships.
                                    //
                                    // Idempotency: this branch is gated by
                                    // `check.pr_url.is_none()` — `pr_url` is set on the
                                    // directive in the same tick above, so a retry of the
                                    // orchestrator will see `check.pr_url.is_some()` and
                                    // skip the hook entirely. Inside the helper we also
                                    // refuse to ship an already-shipped doc as a belt-and-
                                    // braces guard.
                                    if let Err(hook_err) = ship_active_document_for_directive(
                                        &self.pool,
                                        check.directive_id,
                                        &url,
                                    )
                                    .await
                                    {
                                        tracing::warn!(
                                            directive_id = %check.directive_id,
                                            error = %hook_err,
                                            "Failed to ship active directive document — continuing"
                                        );
                                    }
                                }
                                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)
}

/// Ship the currently-active directive document for `directive_id` and seed a
/// fresh empty draft document underneath the same directive.
///
/// Called from the PR-raise completion path the moment the orchestrator
/// extracts a `pr_url` from the completion task's output (see Part 2 of
/// `phase_completion`).
///
/// Selection rule: we only auto-ship when there is **exactly one** document
/// in `status = 'active'`. If there are zero or more than one, we log a TODO
/// and bail out — multi-document selection is the next step's UI work, where
/// the user explicitly chooses which contract a PR ships.
///
/// On success we also auto-create a fresh empty draft document under the
/// same directive (per the goal's "automatically create a new empty draft
/// contract" requirement). The draft sits in `status = 'draft'` until the
/// user starts editing it.
///
/// Idempotency: callers gate on `directive.pr_url.is_none()` so a retried
/// orchestrator tick won't re-fire this. As an extra guard we refuse to
/// ship a doc that is already in `shipped` state.
pub async fn ship_active_document_for_directive(
    pool: &PgPool,
    directive_id: Uuid,
    pr_url: &str,
) -> Result<(), anyhow::Error> {
    // Fetch the directive so we can pick up its pr_branch (set earlier in the
    // completion flow) for the document record.
    let directive = match repository::get_directive(pool, directive_id).await? {
        Some(d) => d,
        None => {
            tracing::warn!(
                directive_id = %directive_id,
                "ship_active_document: directive not found"
            );
            return Ok(());
        }
    };
    let pr_branch = directive.pr_branch.as_deref();

    let docs = repository::list_directive_documents(pool, directive_id).await?;
    let active: Vec<_> = docs
        .iter()
        .filter(|d| d.status == "active")
        .collect();

    match active.len() {
        0 => {
            tracing::info!(
                directive_id = %directive_id,
                "ship_active_document: no active document — nothing to ship"
            );
            return Ok(());
        }
        1 => {}
        n => {
            // TODO(next-step): the new sidebar UI lets users pick which
            // active document a PR ships. Until that lands we conservatively
            // skip — better to leave docs unshipped than to ship the wrong
            // one.
            tracing::warn!(
                directive_id = %directive_id,
                active_count = n,
                "ship_active_document: multiple active documents — leaving unshipped (UI pick coming)"
            );
            return Ok(());
        }
    }

    let target = active[0];

    // Belt-and-braces idempotency: refuse to re-ship.
    if target.status == "shipped" {
        tracing::info!(
            directive_id = %directive_id,
            document_id = %target.id,
            "ship_active_document: document already shipped — skipping"
        );
        return Ok(());
    }

    let shipped = repository::mark_directive_document_shipped(
        pool,
        target.id,
        pr_url,
        pr_branch,
    )
    .await?;
    if let Some(s) = shipped {
        tracing::info!(
            directive_id = %directive_id,
            document_id = %s.id,
            pr_url = %pr_url,
            "Marked directive document as shipped"
        );
    }

    // Auto-create the fresh empty draft contract that succeeds the just-
    // shipped one. Per the directive goal: "automatically create a new
    // empty draft contract".
    match repository::create_directive_document(pool, directive_id, "", "").await {
        Ok(draft) => {
            tracing::info!(
                directive_id = %directive_id,
                document_id = %draft.id,
                "Created fresh empty draft directive document after shipping"
            );
        }
        Err(e) => {
            tracing::warn!(
                directive_id = %directive_id,
                error = %e,
                "Failed to auto-create draft directive document after shipping — continuing"
            );
        }
    }

    Ok(())
}

/// 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 contract_body = repository::get_active_contract_body(pool, directive_id)
        .await
        .unwrap_or_default();
    let prompt = build_completion_prompt(&directive, &contract_body, &step_tasks, &step_branches, &directive_branch, base_branch);

    let task_name = if directive.pr_url.is_some() {
        "completion (update)".to_string()
    } else {
        "completion".to_string()
    };

    // 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)
}

/// Summarize currently-running and recently-completed steps for the planner.
///
/// Returns `None` when there is no in-flight or recently-completed work to
/// report; otherwise returns a multi-line block listing running steps first
/// (these are the ones the planner most needs to be aware of so it doesn't
/// re-issue them) followed by recently completed steps.
fn summarize_in_progress_steps(
    steps: &[crate::db::models::DirectiveStep],
) -> Option<String> {
    let mut running: Vec<&crate::db::models::DirectiveStep> = Vec::new();
    let mut completed: Vec<&crate::db::models::DirectiveStep> = Vec::new();

    for step in steps {
        match step.status.as_str() {
            "running" => running.push(step),
            "completed" => completed.push(step),
            _ => {}
        }
    }

    if running.is_empty() && completed.is_empty() {
        return None;
    }

    let mut out = String::new();
    if !running.is_empty() {
        out.push_str("Currently running:\n");
        for step in &running {
            out.push_str(&format!(
                "  • {} (id: {}){}\n",
                step.name,
                step.id,
                step.description
                    .as_deref()
                    .map(|d| format!(" — {}", d))
                    .unwrap_or_default()
            ));
        }
    }
    if !completed.is_empty() {
        if !running.is_empty() {
            out.push('\n');
        }
        out.push_str("Recently completed (work already done — do not re-issue):\n");
        for step in &completed {
            out.push_str(&format!(
                "  • {} (id: {}){}\n",
                step.name,
                step.id,
                step.description
                    .as_deref()
                    .map(|d| format!(" — {}", d))
                    .unwrap_or_default()
            ));
        }
    }

    Some(out)
}

/// Build the planning prompt for a directive.
///
/// `progress_summary` — when supplied, a `WORK IN PROGRESS` section is rendered
/// near the top of the prompt so the (re)planning task knows what step work is
/// currently in flight or recently completed. This is used by replanning when
/// steps are running but the planner has finished, so the new plan can take
/// in-progress work into account instead of re-issuing it.
fn build_planning_prompt(
    directive: &crate::db::models::Directive,
    existing_steps: &[crate::db::models::DirectiveStep],
    generation: i32,
    contract_body: &str,
    progress_summary: Option<&str>,
    previous_merged_revision: Option<&crate::db::models::DirectiveRevision>,
) -> String {
    let mut prompt = String::new();

    // Amendments to a previously-shipped contract. When the user edits a
    // contract whose prior revision was already merged, the planner needs to
    // reason about the BEFORE→AFTER diff so the new PR reflects only the
    // intended delta, not a from-scratch reinterpretation.
    if let Some(prev) = previous_merged_revision {
        prompt.push_str("── AMENDMENT TO A PREVIOUSLY-MERGED CONTRACT ──\n");
        prompt.push_str(&format!(
            "This contract was previously shipped via PR {} (revision v{}, frozen {}). \
             The user has now edited the contract to amend or extend that work. \
             Plan the new PR as a DELTA on top of the merged prior PR, not a fresh build.\n\n",
            prev.pr_url,
            prev.version,
            prev.frozen_at.format("%Y-%m-%d %H:%M:%S UTC"),
        ));
        prompt.push_str("PREVIOUSLY-MERGED CONTRACT (frozen content):\n");
        prompt.push_str(&prev.content);
        prompt.push_str("\n\nAMENDED CONTRACT (what the user wants now):\n");
        prompt.push_str(contract_body);
        prompt.push_str(
            "\n\nIMPORTANT:\n\
             - Identify what CHANGED between the previously-merged contract and the amended one.\n\
             - Keep work that already shipped — only plan the delta.\n\
             - The amended PR should land on top of master containing JUST the additions/edits \
               implied by the diff, not a re-implementation of the original contract.\n\n",
        );
    }

    if let Some(progress) = progress_summary {
        let trimmed = progress.trim();
        if !trimmed.is_empty() {
            prompt.push_str("── WORK IN PROGRESS ──\n");
            prompt.push_str(
                "Steps from the previous plan are already executing or recently completed. \
                 Take this into account when revising the plan: do not re-issue work that is \
                 already underway, and prefer to extend / refine the in-flight chain rather \
                 than rebuild it.\n\n",
            );
            prompt.push_str(trimmed);
            prompt.push_str("\n\n");
        }
    }

    // Always include the current contract body so the planner has the
    // up-to-date spec, regardless of whether there are existing steps.
    prompt.push_str("CURRENT GOAL (active contract body):\n");
    prompt.push_str(contract_body);
    prompt.push_str("\n\n");

    // Suppress unused warning for `directive` — kept in the signature so
    // callers don't have to plumb the contract body separately when we
    // expand the prompt later.
    let _ = directive;

    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",
        ));

        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"#,
        title = directive.title,
        goal = contract_body,
        repo_section = match &directive.repository_url {
            Some(url) => format!("REPOSITORY: {}\n", url),
            None => String::new(),
        },
    ));

    // The original tail (orders, dependency rules, etc.) follows below;
    // re-attached intact so the prompt structure is unchanged.
    prompt.push_str(r#"

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 (DAG SHAPE — READ CAREFULLY):
- DEFAULT TO STRICTLY LINEAR CHAINS: step1 → step2 → step3 → … each step depends on the previous one.
  This is the right shape for almost every directive. A linear chain inherits each previous step's
  worktree, so later steps can see and build on earlier work, and the final merge is just a fast-forward
  with at most a rebase against the base branch.
- ONLY use parallel steps (same orderIndex, no mutual dependsOn) when the work is GENUINELY independent:
  the steps modify completely disjoint files or modules AND neither needs the other's output.
  Pure-frontend vs pure-backend work in separate folders is the prototypical example. If you can name
  even one shared file or one shared concept, the steps must be sequential.
- WHEN IN DOUBT, MAKE IT SEQUENTIAL. The cost of unnecessary serialization is one extra step run.
  The cost of unnecessary parallelism is merge conflicts, lost work, and a final PR that has to be
  hand-reconciled — exactly the failure mode this rule exists to prevent.
- A directive with N parallel branches is suspicious; a directive with N+1 sequential steps is the norm.
  If you find yourself drawing a diamond (A → {{B, C}} → D), strongly reconsider whether B and C are
  actually independent or whether one should follow the other.

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
"#);

    prompt
}

/// Build the prompt for a completion task that creates or updates a PR.
fn build_completion_prompt(
    directive: &crate::db::models::Directive,
    contract_body: &str,
    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}

NOTE: This directive was planned with the strict-linear-DAG rule, so the step branches
should generally merge cleanly. If a merge produces meaningful conflicts, that is a
signal the plan was wrong, not routine work — prefer asking for help over papering
over conflicts with `-X theirs`.

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}
```

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

## Step 2.5: MANDATORY pre-push verification

Before pushing or creating the PR, you MUST run all three of these checks. Skipping any
of them is a directive failure.

a) Build check — make sure the combined branch compiles:
   - Rust backend (if any backend files changed): `cd makima && cargo check`
   - Frontend (if any frontend files changed): `cd makima/frontend && npm install && npx tsc --noEmit`
   Fix any errors before continuing. Do NOT push broken code.

b) Merge-conflict check — MANDATORY:
```
makima directive verify --base {base_branch}
```
   This must exit 0. If it exits non-zero, the branch will not merge cleanly into
   `{base_branch}` and the PR is not ready. Resolve by:
```
   git fetch origin {base_branch}
   git merge origin/{base_branch}
   # resolve any conflicts, then `git add . && git commit --no-edit`
   makima directive verify --base {base_branch}
```
   Re-run until verify exits 0. Do NOT push, create a PR, or call `makima directive update`
   until verify passes.

c) Goal-alignment self-check:
   Run `git diff origin/{base_branch}...HEAD --stat` and review the file list. Confirm
   the diff actually delivers the directive goal:

       {goal}

   If the diff is missing work the goal requires, finish the work or call
   `makima directive ask "<question>" --phaseguard` for guidance. Do NOT push a PR that
   does not deliver the goal.

3. Push the branch:
```
git push -u origin "$NEW_BRANCH"
```

4. 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.

5. 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.

6. 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 to update the branch (note: do NOT push yet — verification comes first):
```
git fetch origin
git checkout {directive_branch}
git pull origin {directive_branch}
git merge origin/{base_branch} --no-edit
{merge_commands}
```

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

## MANDATORY pre-push verification (also applies to PR updates)

Before `git push`, run all three checks. Skipping any of them is a directive failure.

a) Build check — Rust: `cd makima && cargo check`. Frontend (if changed):
   `cd makima/frontend && npm install && npx tsc --noEmit`. Do NOT push broken code.

b) Merge-conflict check — MANDATORY:
```
makima directive verify --base {base_branch}
```
   Must exit 0. If not, merge `origin/{base_branch}` in, resolve, commit, re-verify.
   Do NOT push until verify passes.

c) Goal-alignment self-check — review `git diff origin/{base_branch}...HEAD --stat`
   and confirm it still delivers the directive goal:

       {goal}

   If the goal has drifted (e.g., new step branches changed scope), update the PR
   description after pushing or call `makima directive ask` for guidance.

Then push:
```
git push origin {directive_branch}
```

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 = contract_body,
            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{}",
                contract_body.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}

NOTE: This directive was planned with the strict-linear-DAG rule, so the step branches
should generally merge cleanly. If a merge produces meaningful conflicts, that is a
signal the plan was wrong, not routine work — prefer asking for help over papering
over conflicts with `-X theirs`.

## Step 1: Build the combined branch (do NOT push yet)
```
git fetch origin
git checkout -b {directive_branch} origin/{base_branch}
{merge_commands}
```

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

## Step 2: MANDATORY pre-push verification

Before pushing or creating the PR, you MUST run all three of these checks. Skipping any
of them is a directive failure.

a) Build check — make sure the combined branch compiles:
   - Rust backend (if any backend files changed): `cd makima && cargo check`
   - Frontend (if any frontend files changed): `cd makima/frontend && npm install && npx tsc --noEmit`
   Fix any errors before continuing. Do NOT push broken code.

b) Merge-conflict check — MANDATORY:
```
makima directive verify --base {base_branch}
```
   This must exit 0. If it exits non-zero, the branch will not merge cleanly into
   `{base_branch}` and the PR is not ready. Resolve by:
```
   git fetch origin {base_branch}
   git merge origin/{base_branch}
   # resolve any conflicts, then `git add . && git commit --no-edit`
   makima directive verify --base {base_branch}
```
   Re-run until verify exits 0. Do NOT push, create a PR, or call `makima directive update`
   until verify passes.

c) Goal-alignment self-check:
   Run `git diff origin/{base_branch}...HEAD --stat` and review the file list. Confirm
   the diff actually delivers the directive goal:

       {goal}

   If the diff is missing work the goal requires, finish the work or call
   `makima directive ask "<question>" --phaseguard` for guidance. Do NOT push a PR that
   does not deliver the goal.

## Step 3: Push and create the PR
```
git push -u origin {directive_branch}
```

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.

## Step 4: Store the PR URL (CRITICAL)

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

1. The `gh pr create` output contains the PR URL (e.g., https://github.com/owner/repo/pull/123)
2. Run:
```
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.

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 = contract_body,
            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{}",
                contract_body.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,
    contract_body: &str,
) -> 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 = contract_body,
        repo_section = match &directive.repository_url {
            Some(url) => format!("REPOSITORY: {}\n", url),
            None => String::new(),
        },
    ));

    // ── 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 (DAG SHAPE — READ CAREFULLY):
- DEFAULT TO STRICTLY LINEAR CHAINS: step1 → step2 → step3 → … each step depends on the previous one.
  This is the right shape for almost every directive. A linear chain inherits each previous step's
  worktree, so later steps can see and build on earlier work, and the final merge is just a fast-forward
  with at most a rebase against the base branch.
- ONLY use parallel steps (same orderIndex, no mutual dependsOn) when the work is GENUINELY independent:
  the steps modify completely disjoint files or modules AND neither needs the other's output.
  Pure-frontend vs pure-backend work in separate folders is the prototypical example. If you can name
  even one shared file or one shared concept, the steps must be sequential.
- WHEN IN DOUBT, MAKE IT SEQUENTIAL. The cost of unnecessary serialization is one extra step run.
  The cost of unnecessary parallelism is merge conflicts, lost work, and a final PR that has to be
  hand-reconciled — exactly the failure mode this rule exists to prevent.
- A directive with N parallel branches is suspicious; a directive with N+1 sequential steps is the norm.

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
}

// =============================================================================
// Planner cancellation helper
// =============================================================================

/// Best-effort cancellation of a directive's currently-running orchestrator
/// (planner) task. Used by the goal-update path: when we are about to clear
/// `orchestrator_task_id` from the directive, the still-running task would
/// otherwise keep emitting `add-step` calls based on the OLD goal, racing the
/// freshly-spawned replanner. We send an `InterruptTask` daemon command and
/// mark the task `interrupted` in the DB so monitoring sees a clean state.
///
/// All errors are logged and translated into `Ok(false)` — the caller's path
/// (clearing orchestrator_task_id, kicking the reconciler) is still safe to
/// proceed.
pub async fn try_cancel_running_planner(
    pool: &PgPool,
    state: &SharedState,
    directive_id: Uuid,
    orchestrator_task_id: Uuid,
) -> Result<bool, anyhow::Error> {
    let task = match repository::get_task(pool, orchestrator_task_id).await? {
        Some(t) => t,
        None => return Ok(false),
    };

    let cancellable = matches!(
        task.status.as_str(),
        "queued" | "pending" | "starting" | "running"
    );
    if !cancellable {
        return Ok(false);
    }

    if let Some(daemon_id) = task.daemon_id {
        let command = DaemonCommand::InterruptTask {
            task_id: orchestrator_task_id,
            graceful: true,
        };
        if let Err(e) = state.send_daemon_command(daemon_id, command).await {
            tracing::warn!(
                directive_id = %directive_id,
                task_id = %orchestrator_task_id,
                daemon_id = %daemon_id,
                error = %e,
                "Failed to dispatch InterruptTask to orphaned planner; will mark interrupted in DB"
            );
        } else {
            tracing::info!(
                directive_id = %directive_id,
                task_id = %orchestrator_task_id,
                daemon_id = %daemon_id,
                "Sent InterruptTask to orphaned planner before clearing orchestrator"
            );
        }
    } else {
        tracing::debug!(
            directive_id = %directive_id,
            task_id = %orchestrator_task_id,
            "Orphaned planner has no daemon assignment; skipping daemon command"
        );
    }

    // Mark the task interrupted regardless of whether the daemon was reachable
    // — this is the source of truth the monitor consults next tick.
    let upd = crate::db::models::UpdateTaskRequest {
        status: Some("interrupted".to_string()),
        version: Some(task.version),
        error_message: Some(
            "Cancelled because the directive's goal was updated".to_string(),
        ),
        ..Default::default()
    };
    if let Err(e) =
        repository::update_task_for_owner(pool, orchestrator_task_id, task.owner_id, upd).await
    {
        tracing::warn!(
            directive_id = %directive_id,
            task_id = %orchestrator_task_id,
            error = %e,
            "Failed to mark orphaned planner interrupted"
        );
    }

    Ok(true)
}

// (Goal-edit classification + interrupt helpers were tied to directive.goal,
// which has been dropped. Their unit tests went with them.)