task_graph_mcp/config/

workflows.rs

//! Workflow configuration for states, phases, and transition prompts.
//!
//! This module defines the unified workflow configuration that combines:
//! - State definitions (exits, timed)
//! - Phase definitions
//! - Transition prompts (enter/exit for states, phases, and combos)

use serde::{Deserialize, Serialize};
use std::collections::{HashMap, HashSet};
use std::sync::Arc;

use super::types::{
    GateDefinition, PhasesConfig, StateDefinition, StatesConfig, UnknownKeyBehavior,
};

/// Definition of an advisory topic for on-demand guidance.
///
/// Advisories are pull-based guidance that agents request via `get_advisory`.
/// Each advisory has content and optional filters for contextual matching.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct AdvisoryDefinition {
    /// Hierarchy levels this advisory applies to (e.g., "epic", "story").
    /// Empty means all levels.
    #[serde(default)]
    pub level: Vec<String>,

    /// Phases this advisory applies to (e.g., "implement", "review").
    /// Empty means all phases.
    #[serde(default)]
    pub phase: Vec<String>,

    /// Roles this advisory applies to (e.g., "lead", "worker").
    /// Empty means all roles.
    #[serde(default)]
    pub role: Vec<String>,

    /// Work domains this advisory applies to (e.g., "engineering", "legal").
    /// Empty means all domains.
    #[serde(default)]
    pub domain: Vec<String>,

    /// The advisory content (supports {{template_vars}}).
    #[serde(default)]
    pub content: String,
}

/// Settings for workflow behavior.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkflowSettings {
    /// Default state for new tasks.
    #[serde(default = "default_initial_state")]
    pub initial_state: String,

    /// State for tasks when agent disconnects (must be untimed).
    #[serde(default = "default_disconnect_state")]
    pub disconnect_state: String,

    /// States that block dependent tasks (tasks in these states count as "not done").
    #[serde(default = "default_blocking_states")]
    pub blocking_states: Vec<String>,

    /// Behavior for unknown phase values (allow, warn, reject).
    #[serde(default)]
    pub unknown_phase: UnknownKeyBehavior,
}

fn default_initial_state() -> String {
    "pending".to_string()
}

fn default_disconnect_state() -> String {
    "pending".to_string()
}

fn default_blocking_states() -> Vec<String> {
    vec![
        "pending".to_string(),
        "assigned".to_string(),
        "working".to_string(),
    ]
}

impl Default for WorkflowSettings {
    fn default() -> Self {
        Self {
            initial_state: default_initial_state(),
            disconnect_state: default_disconnect_state(),
            blocking_states: default_blocking_states(),
            unknown_phase: UnknownKeyBehavior::default(),
        }
    }
}

/// Prompts for state/phase transitions.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct TransitionPrompts {
    /// Prompt shown when entering this state/phase.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enter: Option<String>,

    /// Prompt shown when exiting this state/phase.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exit: Option<String>,
}

/// Definition of a single state in the workflow.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct StateWorkflow {
    /// Allowed states to transition to from this state.
    #[serde(default)]
    pub exits: Vec<String>,

    /// Whether time spent in this state should be tracked.
    #[serde(default)]
    pub timed: bool,

    /// Prompts for entering/exiting this state.
    #[serde(default)]
    pub prompts: TransitionPrompts,
}

/// Definition of a phase in the workflow.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct PhaseWorkflow {
    /// Prompts for entering/exiting this phase.
    #[serde(default)]
    pub prompts: TransitionPrompts,
}

/// Prompts for state+phase combinations.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct ComboPrompts {
    /// Prompt shown when entering this state+phase combination.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub enter: Option<String>,

    /// Prompt shown when exiting this state+phase combination.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub exit: Option<String>,
}

/// Definition of a role in a workflow (e.g., "lead", "worker").
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RoleDefinition {
    /// Human-readable description of this role.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Tags that identify agents in this role.
    #[serde(default)]
    pub tags: Vec<String>,

    /// Maximum number of tasks this role can claim simultaneously.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_claims: Option<u32>,

    /// Whether this role can assign tasks to other agents.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub can_assign: Option<bool>,

    /// Whether this role can create subtasks.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub can_create_subtasks: Option<bool>,
}

/// Unified workflow configuration.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkflowsConfig {
    /// Short identifier for the workflow (e.g., "swarm", "relay", "solo").
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub name: Option<String>,

    /// Human-readable description of the workflow's coordination model.
    /// Should explain when to choose this workflow and how agents coordinate.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub description: Option<String>,

    /// Path to the source file this workflow was loaded from.
    /// Not deserialized from YAML - populated by the loader.
    #[serde(skip)]
    pub source_file: Option<std::path::PathBuf>,

    /// Global workflow settings.
    #[serde(default)]
    pub settings: WorkflowSettings,

    /// State definitions with transitions, timing, and prompts.
    #[serde(default)]
    pub states: HashMap<String, StateWorkflow>,

    /// Phase definitions with prompts.
    #[serde(default)]
    pub phases: HashMap<String, PhaseWorkflow>,

    /// State+phase combination prompts (key format: "state+phase").
    #[serde(default)]
    pub combos: HashMap<String, ComboPrompts>,

    /// Gate definitions for status and phase exits.
    /// Keys are "status:<name>" or "phase:<name>", values are lists of gate definitions.
    #[serde(default)]
    pub gates: HashMap<String, Vec<GateDefinition>>,

    /// Role definitions (e.g., "lead", "worker") with tags, permissions, and constraints.
    #[serde(default)]
    pub roles: HashMap<String, RoleDefinition>,

    /// Role-specific prompts. Outer key is role name, inner key is prompt name
    /// (e.g., "claiming", "completing"), value is the prompt content.
    #[serde(default)]
    pub role_prompts: HashMap<String, HashMap<String, String>>,

    /// Advisory definitions for on-demand guidance.
    /// Key is the advisory topic name (e.g., "decompose-epic", "inject-legal").
    #[serde(default)]
    pub advisories: HashMap<String, AdvisoryDefinition>,

    /// Cache of named workflow configs (e.g., "swarm" -> workflow-swarm.yaml).
    /// Populated at server startup, not serialized.
    #[serde(skip)]
    pub named_workflows: HashMap<String, Arc<WorkflowsConfig>>,

    /// Key to look up the default workflow in named_workflows cache.
    /// If set, workers without a workflow use this instead of the base config.
    #[serde(skip)]
    pub default_workflow_key: Option<String>,

    /// Cache of named overlay configs (e.g., "git" -> overlay-git.yaml).
    /// Overlays are loaded as raw deltas (NOT merged with defaults).
    #[serde(skip)]
    pub named_overlays: HashMap<String, Arc<WorkflowsConfig>>,

    /// Active overlay names applied to this config (for tracking).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub active_overlays: Vec<String>,
}

impl Default for WorkflowsConfig {
    fn default() -> Self {
        Self {
            name: None,
            description: None,
            source_file: None,
            settings: WorkflowSettings::default(),
            states: default_state_workflows(),
            phases: default_phase_workflows(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            advisories: HashMap::new(),
            named_workflows: HashMap::new(),
            default_workflow_key: None,
            named_overlays: HashMap::new(),
            active_overlays: Vec::new(),
        }
    }
}

impl WorkflowsConfig {
    /// Get a named workflow config, or None if not found.
    pub fn get_named_workflow(&self, name: &str) -> Option<&Arc<WorkflowsConfig>> {
        self.named_workflows.get(name)
    }

    /// Get the default workflow config from the cache, if one is configured.
    pub fn get_default_workflow(&self) -> Option<&Arc<WorkflowsConfig>> {
        self.default_workflow_key
            .as_ref()
            .and_then(|key| self.named_workflows.get(key))
    }

    /// Match worker tags to a role defined in this workflow.
    /// Returns the role name if any role's tags overlap with the worker's tags.
    /// If multiple roles match, returns the first match (by sorted key order for determinism).
    pub fn match_role(&self, worker_tags: &[String]) -> Option<String> {
        let mut role_names: Vec<&String> = self.roles.keys().collect();
        role_names.sort();
        for role_name in role_names {
            if let Some(role) = self.roles.get(role_name)
                && role.tags.iter().any(|t| worker_tags.contains(t))
            {
                return Some(role_name.clone());
            }
        }
        None
    }

    /// Get all prompts for a matched role.
    /// Returns an empty HashMap if the role has no prompts defined.
    pub fn get_role_prompts(&self, role_name: &str) -> HashMap<String, String> {
        self.role_prompts
            .get(role_name)
            .cloned()
            .unwrap_or_default()
    }

    /// Get a specific role prompt by role name and prompt key.
    pub fn get_role_prompt(&self, role_name: &str, prompt_key: &str) -> Option<&str> {
        self.role_prompts
            .get(role_name)
            .and_then(|prompts| prompts.get(prompt_key))
            .map(|s| s.as_str())
    }

    /// Get the role definition for a matched role.
    pub fn get_role(&self, role_name: &str) -> Option<&RoleDefinition> {
        self.roles.get(role_name)
    }

    /// Collect all unique role tags across this workflow, all named workflows, and all overlays.
    /// Returns a deduplicated list of tag names used in role definitions.
    pub fn all_role_tags(&self) -> Vec<String> {
        let mut tags = std::collections::HashSet::new();
        // Collect from this workflow's roles
        for role in self.roles.values() {
            for tag in &role.tags {
                tags.insert(tag.clone());
            }
        }
        // Collect from all named workflows
        for workflow in self.named_workflows.values() {
            for role in workflow.roles.values() {
                for tag in &role.tags {
                    tags.insert(tag.clone());
                }
            }
        }
        // Collect from all named overlays
        for overlay in self.named_overlays.values() {
            for role in overlay.roles.values() {
                for tag in &role.tags {
                    tags.insert(tag.clone());
                }
            }
        }
        tags.into_iter().collect()
    }

    /// Apply an overlay on top of this workflow using additive merge semantics.
    ///
    /// Unlike deep-merge (which replaces), overlay merge:
    /// - **states**: union keys; existing states get exits unioned (deduplicated),
    ///   `timed |= overlay.timed`, prompts appended with separator
    /// - **phases**: union keys; existing phases get prompts appended
    /// - **combos**: union keys; existing combos get enter/exit appended
    /// - **gates**: union keys; existing keys extend their Vec (never replace)
    /// - **roles**: union keys; existing roles NOT overridden (first wins)
    /// - **role_prompts**: outer keys unioned; inner keys appended or added
    /// - **settings.initial_state**: overlay wins if it differs from default ("pending")
    /// - **settings.blocking_states**: union (deduplicated)
    pub fn apply_overlay(&mut self, overlay: &WorkflowsConfig) {
        const PROMPT_SEPARATOR: &str = "\n\n---\n\n";

        // --- states ---
        for (name, overlay_state) in &overlay.states {
            if let Some(existing) = self.states.get_mut(name) {
                // Union exits (deduplicated)
                for exit in &overlay_state.exits {
                    if !existing.exits.contains(exit) {
                        existing.exits.push(exit.clone());
                    }
                }
                // timed |= overlay.timed
                existing.timed |= overlay_state.timed;
                // Append prompts
                append_prompt(
                    &mut existing.prompts.enter,
                    &overlay_state.prompts.enter,
                    PROMPT_SEPARATOR,
                );
                append_prompt(
                    &mut existing.prompts.exit,
                    &overlay_state.prompts.exit,
                    PROMPT_SEPARATOR,
                );
            } else {
                self.states.insert(name.clone(), overlay_state.clone());
            }
        }

        // --- phases ---
        for (name, overlay_phase) in &overlay.phases {
            if let Some(existing) = self.phases.get_mut(name) {
                append_prompt(
                    &mut existing.prompts.enter,
                    &overlay_phase.prompts.enter,
                    PROMPT_SEPARATOR,
                );
                append_prompt(
                    &mut existing.prompts.exit,
                    &overlay_phase.prompts.exit,
                    PROMPT_SEPARATOR,
                );
            } else {
                self.phases.insert(name.clone(), overlay_phase.clone());
            }
        }

        // --- combos ---
        for (name, overlay_combo) in &overlay.combos {
            if let Some(existing) = self.combos.get_mut(name) {
                append_optional_prompt(&mut existing.enter, &overlay_combo.enter, PROMPT_SEPARATOR);
                append_optional_prompt(&mut existing.exit, &overlay_combo.exit, PROMPT_SEPARATOR);
            } else {
                self.combos.insert(name.clone(), overlay_combo.clone());
            }
        }

        // --- gates ---
        for (key, overlay_gates) in &overlay.gates {
            self.gates
                .entry(key.clone())
                .or_default()
                .extend(overlay_gates.iter().cloned());
        }

        // --- roles (first wins: existing roles NOT overridden) ---
        for (name, overlay_role) in &overlay.roles {
            self.roles
                .entry(name.clone())
                .or_insert_with(|| overlay_role.clone());
        }

        // --- role_prompts ---
        for (role_name, overlay_prompts) in &overlay.role_prompts {
            let existing = self.role_prompts.entry(role_name.clone()).or_default();
            for (key, overlay_value) in overlay_prompts {
                existing
                    .entry(key.clone())
                    .and_modify(|v| {
                        v.push_str(PROMPT_SEPARATOR);
                        v.push_str(overlay_value);
                    })
                    .or_insert_with(|| overlay_value.clone());
            }
        }

        // --- advisories ---
        for (topic, overlay_advisory) in &overlay.advisories {
            self.advisories
                .entry(topic.clone())
                .and_modify(|existing| {
                    // Append content
                    if !overlay_advisory.content.is_empty() {
                        if !existing.content.is_empty() {
                            existing.content.push_str(PROMPT_SEPARATOR);
                        }
                        existing.content.push_str(&overlay_advisory.content);
                    }
                    // Union filters
                    for v in &overlay_advisory.level {
                        if !existing.level.contains(v) {
                            existing.level.push(v.clone());
                        }
                    }
                    for v in &overlay_advisory.phase {
                        if !existing.phase.contains(v) {
                            existing.phase.push(v.clone());
                        }
                    }
                    for v in &overlay_advisory.role {
                        if !existing.role.contains(v) {
                            existing.role.push(v.clone());
                        }
                    }
                    for v in &overlay_advisory.domain {
                        if !existing.domain.contains(v) {
                            existing.domain.push(v.clone());
                        }
                    }
                })
                .or_insert_with(|| overlay_advisory.clone());
        }

        // --- settings ---
        if overlay.settings.initial_state != default_initial_state() {
            self.settings.initial_state = overlay.settings.initial_state.clone();
        }
        // Union blocking_states (deduplicated)
        for state in &overlay.settings.blocking_states {
            if !self.settings.blocking_states.contains(state) {
                self.settings.blocking_states.push(state.clone());
            }
        }
    }

    /// Compute a diff showing what an overlay changed relative to a base workflow.
    /// Returns a JSON object with added/modified states, exits, gates, and prompts.
    pub fn compute_overlay_diff(&self, base: &WorkflowsConfig) -> serde_json::Value {
        let mut states_added: Vec<String> = Vec::new();
        let mut exits_added: HashMap<String, Vec<String>> = HashMap::new();
        let mut gates_added: Vec<String> = Vec::new();
        let mut prompts_modified: Vec<String> = Vec::new();

        for (name, state) in &self.states {
            if !base.states.contains_key(name) {
                states_added.push(name.clone());
            } else {
                let base_state = &base.states[name];
                // Check for new exits
                let new_exits: Vec<String> = state
                    .exits
                    .iter()
                    .filter(|e| !base_state.exits.contains(e))
                    .cloned()
                    .collect();
                if !new_exits.is_empty() {
                    exits_added.insert(name.clone(), new_exits);
                }
                // Check for modified prompts
                if state.prompts.enter != base_state.prompts.enter {
                    prompts_modified.push(format!("enter~{}", name));
                }
                if state.prompts.exit != base_state.prompts.exit {
                    prompts_modified.push(format!("exit~{}", name));
                }
            }
        }

        for key in self.gates.keys() {
            if !base.gates.contains_key(key) {
                gates_added.push(key.clone());
            } else if self.gates[key].len() > base.gates[key].len() {
                gates_added.push(format!(
                    "{}(+{})",
                    key,
                    self.gates[key].len() - base.gates[key].len()
                ));
            }
        }

        serde_json::json!({
            "states_added": states_added,
            "exits_added": exits_added,
            "gates_added": gates_added,
            "prompts_modified": prompts_modified,
        })
    }
}

/// Append an overlay prompt to an existing Option<String> prompt.
fn append_prompt(target: &mut Option<String>, source: &Option<String>, separator: &str) {
    if let Some(src) = source {
        match target {
            Some(existing) => {
                existing.push_str(separator);
                existing.push_str(src);
            }
            None => *target = Some(src.clone()),
        }
    }
}

/// Append an overlay prompt to an existing Option<String> (combo-style).
fn append_optional_prompt(target: &mut Option<String>, source: &Option<String>, separator: &str) {
    append_prompt(target, source, separator);
}

/// Default state workflow definitions.
fn default_state_workflows() -> HashMap<String, StateWorkflow> {
    let mut states = HashMap::new();

    states.insert(
        "pending".to_string(),
        StateWorkflow {
            exits: vec![
                "assigned".to_string(),
                "working".to_string(),
                "cancelled".to_string(),
            ],
            timed: false,
            prompts: TransitionPrompts::default(),
        },
    );

    states.insert(
        "assigned".to_string(),
        StateWorkflow {
            exits: vec![
                "working".to_string(),
                "pending".to_string(),
                "cancelled".to_string(),
            ],
            timed: false,
            prompts: TransitionPrompts {
                enter: Some(
                    "A task has been assigned to you. Review and claim when ready.".to_string(),
                ),
                exit: None,
            },
        },
    );

    states.insert(
        "working".to_string(),
        StateWorkflow {
            exits: vec![
                "completed".to_string(),
                "failed".to_string(),
                "pending".to_string(),
            ],
            timed: true,
            prompts: TransitionPrompts {
                enter: Some(
                    r#"You are now actively working on this task. Keep your thinking updated regularly using the `thinking` tool to show progress and allow coordination with other agents.

### Heartbeat & Coordination
- Call `thinking(agent=your_id, thought="...")` regularly to maintain heartbeat
- Call `mark_updates(agent=your_id)` every 30-60s during long operations to detect file conflicts
- Stale workers (no heartbeat for 5+ min) get evicted automatically
- The lead monitors worker heartbeats -- stay visible to avoid reassignment

## Valid Next States

From `working` you can transition to:
{{valid_exits}}

Use `update(status="completed")` when done, `update(status="failed")` if blocked, or `update(status="pending")` to release without completing.

## Phase

Current phase: {{current_phase}}

Valid phases: {{valid_phases}}

Set a phase with `update(phase="implement")` to categorize the type of work you're doing.
"#
                        .to_string(),
                ),
                exit: Some(
                    "Before completing:\n- [ ] Unmark files\n- [ ] Attach results or notes\n- [ ] `log_metrics()`".to_string(),
                ),
            },
        },
    );

    states.insert(
        "completed".to_string(),
        StateWorkflow {
            exits: vec!["pending".to_string()],
            timed: false,
            prompts: TransitionPrompts {
                enter: Some("Task completed. Results should be attached.".to_string()),
                exit: None,
            },
        },
    );

    states.insert(
        "failed".to_string(),
        StateWorkflow {
            exits: vec!["pending".to_string()],
            timed: false,
            prompts: TransitionPrompts {
                enter: Some(
                    "Task failed. Document: what was attempted, what blocked, suggested next steps."
                        .to_string(),
                ),
                exit: None,
            },
        },
    );

    states.insert(
        "cancelled".to_string(),
        StateWorkflow {
            exits: Vec::new(),
            timed: false,
            prompts: TransitionPrompts::default(),
        },
    );

    states
}

/// Default phase workflow definitions.
fn default_phase_workflows() -> HashMap<String, PhaseWorkflow> {
    let mut phases = HashMap::new();

    // Phases with prompts
    phases.insert(
        "explore".to_string(),
        PhaseWorkflow {
            prompts: TransitionPrompts {
                enter: None,
                exit: Some(
                    "Capture exploration findings before moving on.\nAttach discoveries to parent task for sibling agents.".to_string(),
                ),
            },
        },
    );

    phases.insert(
        "implement".to_string(),
        PhaseWorkflow {
            prompts: TransitionPrompts {
                enter: Some("Implementation phase. Mark files before editing.".to_string()),
                exit: None,
            },
        },
    );

    phases.insert(
        "review".to_string(),
        PhaseWorkflow {
            prompts: TransitionPrompts {
                enter: Some("Review: tests pass, no new warnings, docs updated.".to_string()),
                exit: None,
            },
        },
    );

    phases.insert(
        "test".to_string(),
        PhaseWorkflow {
            prompts: TransitionPrompts {
                enter: Some(
                    "Testing phase. Verify the implementation works correctly.".to_string(),
                ),
                exit: None,
            },
        },
    );

    phases.insert(
        "security".to_string(),
        PhaseWorkflow {
            prompts: TransitionPrompts {
                enter: Some(
                    "Security: input validation, auth/authz, no secrets in code.".to_string(),
                ),
                exit: None,
            },
        },
    );

    // Phases without prompts
    for phase in &[
        "deliver",
        "triage",
        "diagnose",
        "design",
        "plan",
        "doc",
        "integrate",
        "deploy",
        "monitor",
        "optimize",
    ] {
        phases.insert(phase.to_string(), PhaseWorkflow::default());
    }

    phases
}

impl WorkflowsConfig {
    /// Get the enter prompt for a state.
    pub fn get_state_enter_prompt(&self, state: &str) -> Option<&str> {
        self.states
            .get(state)
            .and_then(|s| s.prompts.enter.as_deref())
    }

    /// Get the exit prompt for a state.
    pub fn get_state_exit_prompt(&self, state: &str) -> Option<&str> {
        self.states
            .get(state)
            .and_then(|s| s.prompts.exit.as_deref())
    }

    /// Get the enter prompt for a phase.
    pub fn get_phase_enter_prompt(&self, phase: &str) -> Option<&str> {
        self.phases
            .get(phase)
            .and_then(|p| p.prompts.enter.as_deref())
    }

    /// Get the exit prompt for a phase.
    pub fn get_phase_exit_prompt(&self, phase: &str) -> Option<&str> {
        self.phases
            .get(phase)
            .and_then(|p| p.prompts.exit.as_deref())
    }

    /// Get the enter prompt for a state+phase combo.
    pub fn get_combo_enter_prompt(&self, state: &str, phase: &str) -> Option<&str> {
        let key = format!("{}+{}", state, phase);
        self.combos.get(&key).and_then(|c| c.enter.as_deref())
    }

    /// Get the exit prompt for a state+phase combo.
    pub fn get_combo_exit_prompt(&self, state: &str, phase: &str) -> Option<&str> {
        let key = format!("{}+{}", state, phase);
        self.combos.get(&key).and_then(|c| c.exit.as_deref())
    }

    /// Get a prompt by trigger name.
    ///
    /// Trigger format:
    /// - `enter~{state}` - entering a state
    /// - `exit~{state}` - exiting a state
    /// - `enter%{phase}` - entering a phase
    /// - `exit%{phase}` - exiting a phase
    /// - `enter~{state}%{phase}` - entering a state+phase combo
    /// - `exit~{state}%{phase}` - exiting a state+phase combo
    pub fn get_prompt(&self, trigger: &str) -> Option<&str> {
        if let Some(rest) = trigger.strip_prefix("enter~") {
            if let Some(idx) = rest.find('%') {
                // Combo: enter~state%phase
                let state = &rest[..idx];
                let phase = &rest[idx + 1..];
                self.get_combo_enter_prompt(state, phase)
            } else {
                // State: enter~state
                self.get_state_enter_prompt(rest)
            }
        } else if let Some(rest) = trigger.strip_prefix("exit~") {
            if let Some(idx) = rest.find('%') {
                // Combo: exit~state%phase
                let state = &rest[..idx];
                let phase = &rest[idx + 1..];
                self.get_combo_exit_prompt(state, phase)
            } else {
                // State: exit~state
                self.get_state_exit_prompt(rest)
            }
        } else if let Some(phase) = trigger.strip_prefix("enter%") {
            self.get_phase_enter_prompt(phase)
        } else if let Some(phase) = trigger.strip_prefix("exit%") {
            self.get_phase_exit_prompt(phase)
        } else {
            None
        }
    }

    /// List all available prompt triggers.
    pub fn list_prompt_triggers(&self) -> Vec<String> {
        let mut triggers = Vec::new();

        // State prompts
        for (state, workflow) in &self.states {
            if workflow.prompts.enter.is_some() {
                triggers.push(format!("enter~{}", state));
            }
            if workflow.prompts.exit.is_some() {
                triggers.push(format!("exit~{}", state));
            }
        }

        // Phase prompts
        for (phase, workflow) in &self.phases {
            if workflow.prompts.enter.is_some() {
                triggers.push(format!("enter%{}", phase));
            }
            if workflow.prompts.exit.is_some() {
                triggers.push(format!("exit%{}", phase));
            }
        }

        // Combo prompts
        for (combo, prompts) in &self.combos {
            if prompts.enter.is_some() {
                triggers.push(format!("enter~{}", combo.replace('+', "%")));
            }
            if prompts.exit.is_some() {
                triggers.push(format!("exit~{}", combo.replace('+', "%")));
            }
        }

        triggers.sort();
        triggers
    }

    /// Get exit gates for a status transition.
    /// Returns gates defined under "status:<name>" key.
    pub fn get_status_exit_gates(&self, status: &str) -> Vec<&GateDefinition> {
        self.gates
            .get(&format!("status:{}", status))
            .map(|v| v.iter().collect())
            .unwrap_or_default()
    }

    /// Get exit gates for a phase transition.
    /// Returns gates defined under "phase:<name>" key.
    pub fn get_phase_exit_gates(&self, phase: &str) -> Vec<&GateDefinition> {
        self.gates
            .get(&format!("phase:{}", phase))
            .map(|v| v.iter().collect())
            .unwrap_or_default()
    }

    /// Get exit gates for a tag.
    /// Returns gates defined under "tag:<tag_name>" key.
    pub fn get_tag_exit_gates(&self, tag: &str) -> Vec<&GateDefinition> {
        self.gates
            .get(&format!("tag:{}", tag))
            .map(|v| v.iter().collect())
            .unwrap_or_default()
    }
}

/// Convert WorkflowsConfig to StatesConfig for backwards compatibility.
impl From<&WorkflowsConfig> for StatesConfig {
    fn from(workflows: &WorkflowsConfig) -> Self {
        let definitions = workflows
            .states
            .iter()
            .map(|(name, workflow)| {
                (
                    name.clone(),
                    StateDefinition {
                        exits: workflow.exits.clone(),
                        timed: workflow.timed,
                    },
                )
            })
            .collect();

        StatesConfig {
            initial: workflows.settings.initial_state.clone(),
            disconnect_state: workflows.settings.disconnect_state.clone(),
            blocking_states: workflows.settings.blocking_states.clone(),
            definitions,
        }
    }
}

/// Convert WorkflowsConfig to PhasesConfig for backwards compatibility.
impl From<&WorkflowsConfig> for PhasesConfig {
    fn from(workflows: &WorkflowsConfig) -> Self {
        let definitions: HashSet<String> = workflows.phases.keys().cloned().collect();

        PhasesConfig {
            unknown_phase: workflows.settings.unknown_phase,
            definitions,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_default_workflows() {
        let workflows = WorkflowsConfig::default();

        // Check settings
        assert_eq!(workflows.settings.initial_state, "pending");
        assert_eq!(workflows.settings.disconnect_state, "pending");
        assert!(
            workflows
                .settings
                .blocking_states
                .contains(&"working".to_string())
        );

        // Check states
        assert!(workflows.states.contains_key("pending"));
        assert!(workflows.states.contains_key("working"));
        assert!(workflows.states.contains_key("completed"));

        // Check working is timed
        assert!(workflows.states.get("working").unwrap().timed);

        // Check phases
        assert!(workflows.phases.contains_key("implement"));
        assert!(workflows.phases.contains_key("test"));
    }

    #[test]
    fn test_get_prompt() {
        let workflows = WorkflowsConfig::default();

        // State enter prompt
        let prompt = workflows.get_prompt("enter~working");
        assert!(prompt.is_some());
        assert!(prompt.unwrap().contains("actively working"));

        // State exit prompt
        let prompt = workflows.get_prompt("exit~working");
        assert!(prompt.is_some());
        assert!(prompt.unwrap().contains("Unmark"));

        // Phase enter prompt
        let prompt = workflows.get_prompt("enter%implement");
        assert!(prompt.is_some());
        assert!(prompt.unwrap().contains("Implementation"));

        // Phase exit prompt
        let prompt = workflows.get_prompt("exit%explore");
        assert!(prompt.is_some());
        assert!(prompt.unwrap().contains("findings"));
    }

    #[test]
    fn test_states_config_from_workflows() {
        let workflows = WorkflowsConfig::default();
        let states: StatesConfig = (&workflows).into();

        assert_eq!(states.initial, "pending");
        assert!(states.definitions.contains_key("working"));
        assert!(states.definitions.get("working").unwrap().timed);
    }

    #[test]
    fn test_phases_config_from_workflows() {
        let workflows = WorkflowsConfig::default();
        let phases: PhasesConfig = (&workflows).into();

        assert!(phases.definitions.contains("implement"));
        assert!(phases.definitions.contains("test"));
    }

    #[test]
    fn test_list_prompt_triggers() {
        let workflows = WorkflowsConfig::default();
        let triggers = workflows.list_prompt_triggers();

        assert!(triggers.contains(&"enter~working".to_string()));
        assert!(triggers.contains(&"exit~working".to_string()));
        assert!(triggers.contains(&"enter%implement".to_string()));
    }

    #[test]
    fn test_all_role_tags_from_base_config() {
        let mut workflows = WorkflowsConfig::default();
        workflows.roles.insert(
            "worker".to_string(),
            RoleDefinition {
                tags: vec!["worker".to_string(), "backend".to_string()],
                ..Default::default()
            },
        );
        workflows.roles.insert(
            "lead".to_string(),
            RoleDefinition {
                tags: vec!["lead".to_string(), "coordinator".to_string()],
                ..Default::default()
            },
        );

        let tags = workflows.all_role_tags();
        assert_eq!(tags.len(), 4);
        assert!(tags.contains(&"worker".to_string()));
        assert!(tags.contains(&"backend".to_string()));
        assert!(tags.contains(&"lead".to_string()));
        assert!(tags.contains(&"coordinator".to_string()));
    }

    #[test]
    fn test_all_role_tags_includes_named_workflows() {
        let mut workflows = WorkflowsConfig::default();

        // Add a named workflow with its own roles
        let mut named = WorkflowsConfig::default();
        named.roles.insert(
            "reviewer".to_string(),
            RoleDefinition {
                tags: vec!["reviewer".to_string()],
                ..Default::default()
            },
        );
        workflows
            .named_workflows
            .insert("review".to_string(), Arc::new(named));

        // Base has no roles, but named workflow does
        let tags = workflows.all_role_tags();
        assert_eq!(tags.len(), 1);
        assert!(tags.contains(&"reviewer".to_string()));
    }

    #[test]
    fn test_all_role_tags_deduplicates() {
        let mut workflows = WorkflowsConfig::default();
        workflows.roles.insert(
            "worker".to_string(),
            RoleDefinition {
                tags: vec!["shared-tag".to_string()],
                ..Default::default()
            },
        );

        let mut named = WorkflowsConfig::default();
        named.roles.insert(
            "builder".to_string(),
            RoleDefinition {
                tags: vec!["shared-tag".to_string()],
                ..Default::default()
            },
        );
        workflows
            .named_workflows
            .insert("build".to_string(), Arc::new(named));

        let tags = workflows.all_role_tags();
        assert_eq!(tags.len(), 1);
        assert!(tags.contains(&"shared-tag".to_string()));
    }

    #[test]
    fn test_apply_overlay_adds_new_state() {
        let mut base = WorkflowsConfig::default();
        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.states.insert(
            "reviewing".to_string(),
            StateWorkflow {
                exits: vec!["completed".to_string()],
                timed: true,
                prompts: TransitionPrompts {
                    enter: Some("Review the changes.".to_string()),
                    exit: None,
                },
            },
        );

        base.apply_overlay(&overlay);
        assert!(base.states.contains_key("reviewing"));
        assert!(base.states["reviewing"].timed);
        assert_eq!(
            base.states["reviewing"].prompts.enter.as_deref(),
            Some("Review the changes.")
        );
    }

    #[test]
    fn test_apply_overlay_appends_prompts() {
        let mut base = WorkflowsConfig::default();
        let original_enter = base.states["working"].prompts.enter.clone();

        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.states.insert(
            "working".to_string(),
            StateWorkflow {
                exits: vec![],
                timed: false,
                prompts: TransitionPrompts {
                    enter: Some("Create a feature branch.".to_string()),
                    exit: None,
                },
            },
        );

        base.apply_overlay(&overlay);
        let enter = base.states["working"].prompts.enter.as_ref().unwrap();
        assert!(enter.contains(&original_enter.unwrap()));
        assert!(enter.contains("Create a feature branch."));
        assert!(enter.contains("---"));
    }

    #[test]
    fn test_apply_overlay_unions_exits() {
        let mut base = WorkflowsConfig::default();
        let original_exits = base.states["working"].exits.clone();

        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.states.insert(
            "working".to_string(),
            StateWorkflow {
                exits: vec!["reviewing".to_string(), "completed".to_string()],
                timed: false,
                prompts: TransitionPrompts::default(),
            },
        );

        base.apply_overlay(&overlay);
        // Should have original exits plus "reviewing" (but not duplicate "completed")
        assert!(
            base.states["working"]
                .exits
                .contains(&"reviewing".to_string())
        );
        for exit in &original_exits {
            assert!(base.states["working"].exits.contains(exit));
        }
    }

    #[test]
    fn test_apply_overlay_extends_gates() {
        let mut base = WorkflowsConfig::default();
        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.gates.insert(
            "status:completed".to_string(),
            vec![GateDefinition {
                gate_type: "gate/commit".to_string(),
                enforcement: super::super::types::GateEnforcement::Warn,
                description: "Changes should be committed.".to_string(),
            }],
        );

        base.apply_overlay(&overlay);
        assert_eq!(base.gates["status:completed"].len(), 1);
        assert_eq!(base.gates["status:completed"][0].gate_type, "gate/commit");
    }

    #[test]
    fn test_apply_overlay_roles_first_wins() {
        let mut base = WorkflowsConfig::default();
        base.roles.insert(
            "worker".to_string(),
            RoleDefinition {
                description: Some("Base worker".to_string()),
                tags: vec!["worker".to_string()],
                ..Default::default()
            },
        );

        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.roles.insert(
            "worker".to_string(),
            RoleDefinition {
                description: Some("Overlay worker".to_string()),
                tags: vec!["overlay-worker".to_string()],
                ..Default::default()
            },
        );

        base.apply_overlay(&overlay);
        // First wins — base description should remain
        assert_eq!(
            base.roles["worker"].description.as_deref(),
            Some("Base worker")
        );
    }

    #[test]
    fn test_compute_overlay_diff() {
        let base = WorkflowsConfig::default();
        let mut merged = base.clone();

        let mut overlay = WorkflowsConfig {
            states: HashMap::new(),
            phases: HashMap::new(),
            combos: HashMap::new(),
            gates: HashMap::new(),
            roles: HashMap::new(),
            role_prompts: HashMap::new(),
            ..Default::default()
        };
        overlay.states.insert(
            "reviewing".to_string(),
            StateWorkflow {
                exits: vec!["completed".to_string()],
                timed: true,
                prompts: TransitionPrompts::default(),
            },
        );
        overlay.states.insert(
            "working".to_string(),
            StateWorkflow {
                exits: vec![],
                timed: false,
                prompts: TransitionPrompts {
                    enter: Some("Git overlay prompt.".to_string()),
                    exit: None,
                },
            },
        );

        merged.apply_overlay(&overlay);
        let diff = merged.compute_overlay_diff(&base);

        let states_added = diff["states_added"].as_array().unwrap();
        assert!(states_added.iter().any(|v| v.as_str() == Some("reviewing")));

        let prompts_modified = diff["prompts_modified"].as_array().unwrap();
        assert!(
            prompts_modified
                .iter()
                .any(|v| v.as_str() == Some("enter~working"))
        );
    }

    #[test]
    fn test_governance_overlay_deserializes() {
        let yaml = include_str!("../../config/overlay-governance.yaml");
        let config: WorkflowsConfig =
            serde_yaml::from_str(yaml).expect("overlay-governance.yaml should deserialize");
        assert_eq!(config.name.as_deref(), Some("governance"));
        assert!(
            !config.advisories.is_empty(),
            "should have advisories defined"
        );
        assert!(!config.gates.is_empty(), "should have gates defined");
    }

    #[test]
    fn test_governance_overlay_advisories() {
        let yaml = include_str!("../../config/overlay-governance.yaml");
        let config: WorkflowsConfig = serde_yaml::from_str(yaml).unwrap();

        // Check key advisories exist
        assert!(config.advisories.contains_key("decompose-vision"));
        assert!(config.advisories.contains_key("decompose-epic"));
        assert!(config.advisories.contains_key("inject-legal"));
        assert!(config.advisories.contains_key("gotchas"));

        // Check advisory filters
        let decompose_epic = &config.advisories["decompose-epic"];
        assert!(decompose_epic.level.contains(&"epic".to_string()));
        assert!(!decompose_epic.content.is_empty());

        let inject_legal = &config.advisories["inject-legal"];
        assert!(inject_legal.domain.contains(&"legal".to_string()));
    }

    #[test]
    fn test_governance_overlay_tag_gates() {
        let yaml = include_str!("../../config/overlay-governance.yaml");
        let config: WorkflowsConfig = serde_yaml::from_str(yaml).unwrap();

        // Check tag-based gates
        let initiative_gates = config.get_tag_exit_gates("level:initiative");
        assert!(
            !initiative_gates.is_empty(),
            "should have gates for level:initiative"
        );
        assert!(
            initiative_gates
                .iter()
                .any(|g| g.gate_type == "gate/business-approval"),
            "should have business-approval gate"
        );

        let legal_gates = config.get_tag_exit_gates("domain:legal");
        assert!(
            legal_gates
                .iter()
                .any(|g| g.gate_type == "gate/legal-sign-off"),
            "should have legal-sign-off gate"
        );
    }

    #[test]
    fn test_advisory_overlay_merge() {
        let mut base = WorkflowsConfig::default();
        let yaml = include_str!("../../config/overlay-governance.yaml");
        let overlay: WorkflowsConfig = serde_yaml::from_str(yaml).unwrap();

        assert!(base.advisories.is_empty());
        base.apply_overlay(&overlay);
        assert!(
            !base.advisories.is_empty(),
            "advisories should be merged from overlay"
        );
        assert!(
            !base.gates.is_empty(),
            "gates should be merged from overlay"
        );
        assert!(base.advisories.contains_key("decompose-epic"));
    }

    #[test]
    fn test_get_tag_exit_gates_empty() {
        let config = WorkflowsConfig::default();
        let gates = config.get_tag_exit_gates("level:nonexistent");
        assert!(gates.is_empty());
    }

    #[test]
    fn test_git_worktree_overlay_deserializes() {
        let yaml = include_str!("../../config/overlay-git-worktree.yaml");
        let config: WorkflowsConfig =
            serde_yaml::from_str(yaml).expect("overlay-git-worktree.yaml should deserialize");
        assert_eq!(config.name.as_deref(), Some("git-worktree"));
        assert!(!config.states.is_empty(), "should have states defined");
        assert!(!config.gates.is_empty(), "should have gates defined");
        assert!(
            !config.advisories.is_empty(),
            "should have advisories defined"
        );
    }

    #[test]
    fn test_git_worktree_overlay_patching_state() {
        let yaml = include_str!("../../config/overlay-git-worktree.yaml");
        let config: WorkflowsConfig = serde_yaml::from_str(yaml).unwrap();

        let patching = config
            .states
            .get("patching")
            .expect("should have patching state");
        assert!(patching.timed, "patching state should be timed");
        assert!(
            patching.exits.contains(&"working".to_string()),
            "patching should exit to working"
        );
        assert!(
            patching.exits.contains(&"completed".to_string()),
            "patching should exit to completed"
        );
        assert!(
            patching.exits.contains(&"failed".to_string()),
            "patching should exit to failed"
        );
    }

    #[test]
    fn test_git_worktree_overlay_composes_with_git() {
        let git_yaml = include_str!("../../config/overlay-git.yaml");
        let worktree_yaml = include_str!("../../config/overlay-git-worktree.yaml");

        let git_overlay: WorkflowsConfig = serde_yaml::from_str(git_yaml).unwrap();
        let worktree_overlay: WorkflowsConfig = serde_yaml::from_str(worktree_yaml).unwrap();

        let mut merged = WorkflowsConfig::default();
        merged.apply_overlay(&git_overlay);
        merged.apply_overlay(&worktree_overlay);

        // Both overlays contribute states
        assert!(
            merged.states.contains_key("working"),
            "should have working state from both overlays"
        );
        assert!(
            merged.states.contains_key("patching"),
            "should have patching state from worktree overlay"
        );
        assert!(
            merged.states.contains_key("completed"),
            "should have completed state from both overlays"
        );

        // Both overlays contribute gates
        let completed_gates = merged
            .gates
            .get("status:completed")
            .expect("should have status:completed gates");
        assert!(
            completed_gates.iter().any(|g| g.gate_type == "gate/commit"),
            "should have gate/commit from git overlay"
        );
        assert!(
            completed_gates.iter().any(|g| g.gate_type == "gate/patch"),
            "should have gate/patch from worktree overlay"
        );

        // Worktree overlay contributes role prompts
        assert!(
            merged.role_prompts.contains_key("integrator"),
            "should have integrator role prompts"
        );

        // Working state prompts are appended (both overlays contribute)
        let working = &merged.states["working"];
        let enter_prompt = working.prompts.enter.as_deref().unwrap_or("");
        assert!(
            enter_prompt.contains("worktree"),
            "working enter prompt should include worktree guidance"
        );
        assert!(
            enter_prompt.contains("branch"),
            "working enter prompt should include branch guidance from git overlay"
        );
    }
}