deepstrike_core/orchestration/workflow/

mod.rs

//! Declarative workflow shapes — the six patterns as composable templates.
//!
//! A [`WorkflowSpec`] is a pure, declarative DAG of [`WorkflowNode`]s, each carrying the
//! per-node execution contract (role / isolation / context inheritance / model hint) that
//! the SDK turns into an `AgentRunSpec` at spawn time. This is the data the template
//! constructors below emit, and the shape a future "orchestration-as-syscall" round will
//! lower into per-step [`crate::syscall::Syscall`]s.
//!
//! Three patterns are template constructors here. The dynamic control-flow patterns —
//! loop-until-done, classify-and-act, and tournament — are now first-class [`NodeKind`] variants
//! ([`NodeKind::Loop`] / [`NodeKind::Classify`] / [`NodeKind::Tournament`]) driven by the unified
//! workflow executor; the former standalone `loop_until_done` / `tournament` SDK primitives were
//! removed in their favor (A#1). The generate→evaluate→retry quality gate is the [`gen_eval`]
//! template (a `Loop` worker + a `Verify` eval node carrying [`crate::harness::verdict_output_schema`]);
//! its eval/verdict compute lives in [`crate::harness`].
//!
//! Pure: no I/O, no clock, no spawning. Validation reuses [`TaskGraph::topological_sort`].

use serde::{Deserialize, Serialize};

use super::task_graph::TaskGraph;
use crate::types::agent::{AgentIsolation, AgentRole, ContextInheritance};
use crate::types::error::{DeepStrikeError, Result};
use crate::types::task::RuntimeTask;

/// The kernel-resident execution state for an in-flight [`WorkflowSpec`] — the DAG run-queue,
/// tournament bracket advancement, and per-node spawn descriptors. Was `scheduler/workflow_run.rs`;
/// folded under `workflow` so the declarative spec and its runtime live in one module.
pub mod run;
pub use run::*;

/// W3: a node's trust level. `Quarantined` nodes read untrusted content and must run with no
/// privileges; their output crosses into the trusted plane only as a structured summary (the SDK
/// enforces this — the kernel carries the flag to every spawn descriptor).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum NodeTrust {
    #[default]
    Trusted,
    Quarantined,
}

/// One branch of a [`NodeKind::Classify`] node: a label and the node indices to enable when the
/// classifier's result selects that label. The other branches' nodes are pruned (failed) so they
/// never run — this is how a classify node yields *conditional edges* in an otherwise static DAG.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ClassifyBranch {
    pub label: String,
    pub nodes: Vec<usize>,
}

/// Control-flow kind of a workflow node. `Spawn` (the default) runs the node's agent once.
/// `Loop` re-runs it until a stop condition; `Classify` routes to one branch by its result;
/// `Tournament` generates entrants and pairwise-judges them — all dynamic control-flow types.
/// Additive: existing specs omit `kind` → `Spawn`. (No `Eq`: a `Tournament`'s entrant tasks carry
/// arbitrary JSON metadata, which is `PartialEq` but not `Eq`.)
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum NodeKind {
    /// Run the node's agent once (classic spawn node).
    #[default]
    Spawn,
    /// Re-run the node's agent up to `max_iters` times; an iteration reporting
    /// `loop_continue=Some(false)` stops early (v2 "until done").
    Loop { max_iters: usize },
    /// Run the node's agent once as a classifier; its `classify_branch` result selects one branch
    /// to run and prunes the others. Branch nodes must `depends_on` this classify node.
    ///
    /// NOTE (W-11): prefer expressing classify-and-act via *runtime submission* — run the
    /// classifier as a plain node and have it `submit_workflow_nodes` only the chosen branch. That
    /// form needs no branch pre-declaration, prune bookkeeping, or resume branch-replay, and is the
    /// CC-parity model-driven shape. `Classify` stays for declaratively auditable topologies (the
    /// full branch set is visible up front) but should not grow new capabilities.
    Classify { branches: Vec<ClassifyBranch> },
    /// A *controller* node (spawns no agent of its own): it generates `entrants` candidates in
    /// parallel, then runs a single-elimination bracket of pairwise judges (reusing
    /// [`super::tournament::Tournament`]) until one survivor remains. The winner's id lands in the
    /// node's `tournament_winner` result; dependents start only after the bracket resolves.
    Tournament { entrants: Vec<RuntimeTask> },
    /// G2 deterministic compute: a *host-compute* node that runs no LLM agent. The kernel schedules
    /// it like a `Spawn` (deps / ready / completion) but stamps its spawn descriptor with `reducer`
    /// + the dependency agent ids, and the SDK routes it to a registered pure function over those
    /// dependencies' outputs (dedupe / filter / merge / early-exit) instead of the model. This is the
    /// "ordinary code between stages" of the code-orchestration model, expressed as a DAG node — no
    /// agent burned, fully deterministic. `reducer` names the SDK-side function.
    Reduce { reducer: String },
}

/// One node in a workflow DAG: a task plus the contract its agent runs under.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct WorkflowNode {
    pub task: RuntimeTask,
    pub role: AgentRole,
    pub isolation: AgentIsolation,
    pub context_inheritance: ContextInheritance,
    /// Optional model preference (e.g. "opus" / "sonnet"); the SDK resolves it. See W4.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub model_hint: Option<String>,
    /// W3 trust level. Default `Trusted`.
    #[serde(default, skip_serializing_if = "is_trusted")]
    pub trust: NodeTrust,
    /// G3 structured output: an optional JSON Schema the node's agent output must conform to. The
    /// kernel is zero-I/O and never validates it — it carries the schema verbatim to the spawn
    /// descriptor so the SDK can instruct the agent and validate/retry on its result (the structured
    /// "summary only" contract from image 8 is enforced SDK-side; the kernel owns the contract).
    /// Additive: omitted on the wire when absent.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub output_schema: Option<serde_json::Value>,
    /// Control-flow kind. Default `Spawn` (run once).
    #[serde(default, skip_serializing_if = "is_spawn")]
    pub kind: NodeKind,
    /// M4/G5: optional per-node cumulative token cap. The kernel carries it to the spawn descriptor;
    /// the SDK sets the node's child-run `max_total_tokens` to it, so an expensive node self-terminates
    /// at the cap (the "use N tokens" budget, applied per node). Additive: omitted on the wire when
    /// `None`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub token_budget: Option<u64>,
    /// O3 per-node turn cap: the SDK sets the child run's `max_turns` (falls back to the parent's).
    /// Mirrors `token_budget` — same hop chain, additive ABI.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_turns: Option<u32>,
    /// O3 per-node wall-clock cap (ms): the SDK sets the child run's timeout. Additive ABI.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_wall_ms: Option<u64>,
    /// Indices into [`WorkflowSpec::nodes`] this node depends on.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub depends_on: Vec<usize>,
}

fn is_trusted(t: &NodeTrust) -> bool {
    matches!(t, NodeTrust::Trusted)
}

fn is_spawn(k: &NodeKind) -> bool {
    matches!(k, NodeKind::Spawn)
}

impl WorkflowNode {
    /// A node with role-default isolation/inheritance and no dependencies.
    pub fn new(task: RuntimeTask, role: AgentRole) -> Self {
        let (isolation, context_inheritance) = role_defaults(role);
        Self {
            task,
            role,
            isolation,
            context_inheritance,
            model_hint: None,
            trust: NodeTrust::Trusted,
            output_schema: None,
            kind: NodeKind::Spawn,
            token_budget: None,
            max_turns: None,
            max_wall_ms: None,
            depends_on: Vec::new(),
        }
    }

    /// M4/G5: cap this node's child run at `tokens` cumulative tokens.
    pub fn with_token_budget(mut self, tokens: u64) -> Self {
        self.token_budget = Some(tokens);
        self
    }

    /// O3: cap this node's child run at `turns` provider turns.
    pub fn with_max_turns(mut self, turns: u32) -> Self {
        self.max_turns = Some(turns);
        self
    }

    /// O3: cap this node's child run at `ms` wall-clock milliseconds.
    pub fn with_max_wall_ms(mut self, ms: u64) -> Self {
        self.max_wall_ms = Some(ms);
        self
    }

    /// Make this a loop node: re-run the agent up to `max_iters` times before completing.
    /// Dependents wait for the whole loop to finish.
    pub fn with_loop(mut self, max_iters: usize) -> Self {
        self.kind = NodeKind::Loop { max_iters };
        self
    }

    /// Make this a classify node: its result selects one of `branches` to run; the rest are pruned.
    pub fn with_classify(mut self, branches: Vec<ClassifyBranch>) -> Self {
        self.kind = NodeKind::Classify { branches };
        self
    }

    /// Make this a tournament *controller* node: it spawns no agent of its own but generates each
    /// of `entrants` (in parallel), then pairwise-judges them to a single winner. The node's own
    /// `task.goal` is the judging criterion handed to every judge. Requires ≥2 entrants.
    pub fn with_tournament(mut self, entrants: Vec<RuntimeTask>) -> Self {
        self.kind = NodeKind::Tournament { entrants };
        self
    }

    /// G2: make this a deterministic *reduce* node — it runs no LLM agent; the SDK routes it to the
    /// registered `reducer` function over its dependencies' outputs (dedupe / filter / merge). Give
    /// it `depends_on` the nodes whose outputs it consumes.
    pub fn with_reduce(mut self, reducer: impl Into<String>) -> Self {
        self.kind = NodeKind::Reduce { reducer: reducer.into() };
        self
    }

    pub fn with_depends_on(mut self, depends_on: Vec<usize>) -> Self {
        self.depends_on = depends_on;
        self
    }

    pub fn with_isolation(mut self, isolation: AgentIsolation) -> Self {
        self.isolation = isolation;
        self
    }

        pub fn with_model_hint(mut self, hint: impl Into<String>) -> Self {
        self.model_hint = Some(hint.into());
        self
    }

    /// W3: mark this node's trust level. `Quarantined` nodes read untrusted content and are
    /// kernel-enforced to read-only (a quarantined node declaring write isolation is denied).
    pub fn with_trust(mut self, trust: NodeTrust) -> Self {
        self.trust = trust;
        self
    }

    /// Mark this node as quarantined (reads untrusted content, runs without privileges).
    pub fn quarantined(mut self) -> Self {
        self.trust = NodeTrust::Quarantined;
        self
    }

    /// G3: require this node's output to conform to a JSON Schema. The kernel carries it verbatim to
    /// the spawn descriptor; the SDK instructs the agent and validates/retries on its result.
    pub fn with_output_schema(mut self, schema: serde_json::Value) -> Self {
        self.output_schema = Some(schema);
        self
    }
}

/// Role-appropriate defaults for a freshly templated node. Verifiers/explorers run
/// read-only with minimal inherited context to resist self-preferential bias.
fn role_defaults(role: AgentRole) -> (AgentIsolation, ContextInheritance) {
    match role {
        AgentRole::Explore => (AgentIsolation::ReadOnly, ContextInheritance::SystemOnly),
        AgentRole::Verify => (AgentIsolation::ReadOnly, ContextInheritance::None),
        AgentRole::Plan => (AgentIsolation::Shared, ContextInheritance::Full),
        AgentRole::Implement => (AgentIsolation::Worktree, ContextInheritance::Full),
        AgentRole::Custom => (AgentIsolation::Shared, ContextInheritance::None),
    }
}

/// A declarative workflow DAG.
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct WorkflowSpec {
    pub nodes: Vec<WorkflowNode>,
}

impl WorkflowSpec {
    pub fn new(nodes: Vec<WorkflowNode>) -> Self {
        Self { nodes }
    }

    /// Validate dependency indices are in range and the graph is acyclic.
    pub fn validate(&self) -> Result<TaskGraph> {
        let n = self.nodes.len();
        for (i, node) in self.nodes.iter().enumerate() {
            if let NodeKind::Loop { max_iters: 0 } = node.kind {
                return Err(DeepStrikeError::InvalidConfig(format!(
                    "node {i} is a loop with max_iters=0 (would never run)"
                )));
            }
            if let NodeKind::Tournament { entrants } = &node.kind {
                if entrants.len() < 2 {
                    return Err(DeepStrikeError::InvalidConfig(format!(
                        "tournament node {i} needs at least 2 entrants (have {})",
                        entrants.len()
                    )));
                }
            }
            if let NodeKind::Classify { branches } = &node.kind {
                for branch in branches {
                    for &bn in &branch.nodes {
                        if bn >= n {
                            return Err(DeepStrikeError::InvalidConfig(format!(
                                "classify node {i} branch '{}' references out-of-range node {bn}",
                                branch.label
                            )));
                        }
                        // Branch nodes must be gated by the classifier, else they'd run before
                        // classification and the prune would come too late.
                        if !self.nodes[bn].depends_on.contains(&i) {
                            return Err(DeepStrikeError::InvalidConfig(format!(
                                "classify node {i} branch '{}' node {bn} must depends_on {i}",
                                branch.label
                            )));
                        }
                    }
                }
            }
            for &dep in &node.depends_on {
                if dep >= n {
                    return Err(DeepStrikeError::InvalidConfig(format!(
                        "node {i} depends on out-of-range node {dep} (have {n})"
                    )));
                }
                if dep == i {
                    return Err(DeepStrikeError::InvalidConfig(format!(
                        "node {i} depends on itself"
                    )));
                }
            }
        }
        // Reuse the executor's cycle detection; hand the built graph back so callers
        // that need it (WorkflowRun::new) don't lower + range-check a second time.
        let graph = self.to_task_graph()?;
        graph.topological_sort()?;
        Ok(graph)
    }

    /// Lower into an executable [`TaskGraph`] (preserves node order as task ids).
    pub fn to_task_graph(&self) -> Result<TaskGraph> {
        let n = self.nodes.len();
        let mut graph = TaskGraph::new();
        for node in &self.nodes {
            if let Some(&bad) = node.depends_on.iter().find(|&&d| d >= n) {
                return Err(DeepStrikeError::InvalidConfig(format!(
                    "dependency index {bad} out of range (have {n})"
                )));
            }
            graph.add(node.task.clone(), node.depends_on.clone());
        }
        Ok(graph)
    }
}

// ---------------------------------------------------------------------------
// Pattern 1 — Fan-out-and-synthesize
// ---------------------------------------------------------------------------

/// N parallel workers feeding a single synthesize barrier that depends on all of them.
///
/// Workers run as read-only `Explore` agents in the `Retrieve` lane (parallelisable, each
/// with its own clean context); the synthesizer is a `Plan` agent that merges their
/// structured outputs.
pub fn fanout_synthesize(workers: Vec<RuntimeTask>, synthesize: RuntimeTask) -> WorkflowSpec {
    let mut nodes: Vec<WorkflowNode> = workers
        .into_iter()
        .map(|t| WorkflowNode::new(t, AgentRole::Explore))
        .collect();
    let worker_ids: Vec<usize> = (0..nodes.len()).collect();
    nodes.push(
        WorkflowNode::new(synthesize, AgentRole::Plan)
            .with_depends_on(worker_ids),
    );
    WorkflowSpec::new(nodes)
}

// ---------------------------------------------------------------------------
// Pattern 2 — Generate-and-filter
// ---------------------------------------------------------------------------

/// N parallel generators feeding a single filter/dedupe step that depends on all of them.
///
/// Structurally a fan-out barrier, but semantically distinct: generators are `Implement`
/// agents producing candidates; the filter is a `Verify` agent that ranks/dedupes against
/// a rubric (pair with the [`gen_eval`] verdict schema for the rubric).
pub fn generate_and_filter(generators: Vec<RuntimeTask>, filter: RuntimeTask) -> WorkflowSpec {
    let mut nodes: Vec<WorkflowNode> = generators
        .into_iter()
        .map(|t| WorkflowNode::new(t, AgentRole::Implement))
        .collect();
    let gen_ids: Vec<usize> = (0..nodes.len()).collect();
    nodes.push(
        WorkflowNode::new(filter, AgentRole::Verify)
            .with_depends_on(gen_ids),
    );
    WorkflowSpec::new(nodes)
}

// ---------------------------------------------------------------------------
// W2 — Adversarial verification (the default contract)
// ---------------------------------------------------------------------------

/// One fresh-context verifier per rule/claim, optionally followed by a skeptic that re-checks
/// every flag to suppress false positives.
///
/// This is the article's rule-adherence pattern. Each verifier runs as a `Verify` agent, which
/// [`role_defaults`] gives `ReadOnly` isolation + [`ContextInheritance::None`] — the verifier does
/// **not** inherit the author's reasoning, so it cannot rubber-stamp it (the structural defence
/// against self-preferential bias). The optional `skeptic` depends on all verifiers and reviews
/// their flags (real violation vs. false positive). Runs on the W0 workflow executor.
///
/// For unknown-size rule sets (claim extraction), a dynamic-fan-out variant is a later round; this
/// covers the case where the rule/claim set is known up front. For the generate→evaluate→retry
/// quality gate (scoring one author's output against criteria), see [`gen_eval`].
pub fn verify_rules(rules: Vec<RuntimeTask>, skeptic: Option<RuntimeTask>) -> WorkflowSpec {
    let mut nodes: Vec<WorkflowNode> = rules
        .into_iter()
        .map(|t| WorkflowNode::new(t, AgentRole::Verify))
        .collect();
    if let Some(skeptic) = skeptic {
        let verifier_ids: Vec<usize> = (0..nodes.len()).collect();
        nodes.push(
            WorkflowNode::new(skeptic, AgentRole::Verify)
                .with_depends_on(verifier_ids),
        );
    }
    WorkflowSpec::new(nodes)
}

// ---------------------------------------------------------------------------
// Quality gate — generate → evaluate (#6, the EvalPipeline successor)
// ---------------------------------------------------------------------------

/// The generate→evaluate quality gate as a workflow: a `Loop` **worker** node (the task, re-run up
/// to `max_iters`, stopping early on a `loop_continue=false` self-signal) followed by a `Verify`
/// **eval** node that scores the worker's output against the goal/criteria and emits a structured
/// verdict ([`crate::harness::verdict_output_schema`] as its `output_schema`).
///
/// This is the declarative substrate form of the former `EvalPipeline` (0.5.0 fold, OS-axis #6).
/// The eval node is a `Verify` agent — [`role_defaults`] gives it `ReadOnly` + [`ContextInheritance::None`]
/// so it does not inherit the worker's reasoning (bias resistance); it evaluates the worker's
/// *output*, carried in via its task goal. The verdict's `passed` is the gate.
///
/// For the **iterative retry-with-feedback** variant (re-run the worker with the eval's feedback
/// folded into the next attempt), the SDK `HarnessLoop` drives this with the same
/// [`crate::harness::build_eval_messages`] / [`crate::harness::parse_verdict`] primitives — the
/// kernel `Loop` re-arms a single node, so per-iteration eval is necessarily SDK-driven.
pub fn gen_eval(
    worker: RuntimeTask,
    eval: RuntimeTask,
    max_iters: usize,
    extract_skill_on_pass: bool,
) -> WorkflowSpec {
    let worker_node = WorkflowNode::new(
        worker,
        AgentRole::Implement,
    )
    .with_loop(max_iters.max(1));
    let eval_node = WorkflowNode::new(
        eval,
        AgentRole::Verify,
    )
    .with_depends_on(vec![0])
    .with_output_schema(crate::harness::verdict_output_schema(extract_skill_on_pass));
    WorkflowSpec::new(vec![worker_node, eval_node])
}

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

    fn task(goal: &str) -> RuntimeTask {
        RuntimeTask::new(goal)
    }

    #[test]
    fn fanout_synthesize_shape() {
        let spec = fanout_synthesize(
            vec![task("search A"), task("search B"), task("search C")],
            task("merge findings"),
        );
        assert_eq!(spec.nodes.len(), 4);
        // synthesize node depends on all three workers
        assert_eq!(spec.nodes[3].depends_on, vec![0, 1, 2]);
        assert_eq!(spec.nodes[3].role, AgentRole::Plan);
        assert_eq!(spec.nodes[0].role, AgentRole::Explore);
        assert_eq!(spec.nodes[0].isolation, AgentIsolation::ReadOnly);
        spec.validate().unwrap();
        // workers are the only ready tasks before any completion
        let graph = spec.to_task_graph().unwrap();
        assert_eq!(graph.ready_tasks(), vec![0, 1, 2]);
    }

    #[test]
    fn generate_and_filter_shape() {
        let spec = generate_and_filter(vec![task("idea 1"), task("idea 2")], task("dedupe + rank"));
        assert_eq!(spec.nodes.len(), 3);
        assert_eq!(spec.nodes[2].depends_on, vec![0, 1]);
        assert_eq!(spec.nodes[2].role, AgentRole::Verify);
        assert_eq!(spec.nodes[2].context_inheritance, ContextInheritance::None);
        assert_eq!(spec.nodes[0].role, AgentRole::Implement);
        spec.validate().unwrap();
    }

    #[test]
    fn verify_rules_with_skeptic_shape() {
        let spec = verify_rules(
            vec![task("money is integer cents"), task("errors propagate"), task("utc timestamps")],
            Some(task("skeptic: real violation or false positive?")),
        );
        assert_eq!(spec.nodes.len(), 4);
        // skeptic depends on every verifier
        assert_eq!(spec.nodes[3].depends_on, vec![0, 1, 2]);
        assert_eq!(spec.nodes[3].role, AgentRole::Verify);
        spec.validate().unwrap();
        // verifiers are the ready set; skeptic gated behind them
        assert_eq!(spec.to_task_graph().unwrap().ready_tasks(), vec![0, 1, 2]);
    }

    #[test]
    fn verify_rules_verifiers_are_bias_resistant() {
        // The default contract: every verifier runs with no inherited author context.
        let spec = verify_rules(vec![task("rule a"), task("rule b")], None);
        assert_eq!(spec.nodes.len(), 2); // no skeptic → just the verifiers
        for node in &spec.nodes {
            assert_eq!(node.role, AgentRole::Verify);
            assert_eq!(node.context_inheritance, ContextInheritance::None);
            assert_eq!(node.isolation, AgentIsolation::ReadOnly);
            assert!(node.depends_on.is_empty()); // all parallel
        }
        spec.validate().unwrap();
    }

    #[test]
    fn gen_eval_shape() {
        // Worker loops; eval is a bias-resistant Verify node gated on the worker, carrying the
        // verdict output_schema.
        let spec = gen_eval(task("implement feature"), task("score against criteria"), 3, true);
        assert_eq!(spec.nodes.len(), 2);

        let worker = &spec.nodes[0];
        assert_eq!(worker.role, AgentRole::Implement);
        assert_eq!(worker.kind, NodeKind::Loop { max_iters: 3 });
        assert!(worker.depends_on.is_empty());

        let eval = &spec.nodes[1];
        assert_eq!(eval.role, AgentRole::Verify);
        assert_eq!(eval.context_inheritance, ContextInheritance::None);
        assert_eq!(eval.isolation, AgentIsolation::ReadOnly);
        assert_eq!(eval.depends_on, vec![0]);
        let schema = eval.output_schema.as_ref().expect("eval node carries verdict schema");
        assert!(schema["properties"]["passed"].is_object());
        assert!(schema["properties"]["skill"].is_object()); // extract_skill_on_pass=true

        spec.validate().unwrap();
        // Worker is the only initially-ready node; eval is gated.
        assert_eq!(spec.to_task_graph().unwrap().ready_tasks(), vec![0]);
    }

    #[test]
    fn gen_eval_max_iters_floor_and_no_skill() {
        // max_iters=0 would be an invalid loop; the template floors it to 1.
        let spec = gen_eval(task("w"), task("e"), 0, false);
        assert_eq!(spec.nodes[0].kind, NodeKind::Loop { max_iters: 1 });
        // extract_skill_on_pass=false ⇒ no skill property in the verdict schema.
        let schema = spec.nodes[1].output_schema.as_ref().unwrap();
        assert!(schema["properties"]["skill"].is_null());
        spec.validate().unwrap();
    }

    #[test]
    fn verify_rules_empty_with_skeptic_is_just_skeptic() {
        // No rules → skeptic has nothing to depend on; still a valid single-node spec.
        let spec = verify_rules(vec![], Some(task("skeptic")));
        assert_eq!(spec.nodes.len(), 1);
        assert!(spec.nodes[0].depends_on.is_empty());
        spec.validate().unwrap();
    }

    #[test]
    fn validate_rejects_out_of_range_dep() {
        let spec = WorkflowSpec::new(vec![
            WorkflowNode::new(task("a"), AgentRole::Explore),
            WorkflowNode::new(task("b"), AgentRole::Plan).with_depends_on(vec![5]),
        ]);
        assert!(spec.validate().is_err());
    }

    #[test]
    fn validate_rejects_self_dependency() {
        let spec = WorkflowSpec::new(vec![
            WorkflowNode::new(task("a"), AgentRole::Plan).with_depends_on(vec![0]),
        ]);
        assert!(spec.validate().is_err());
    }

    #[test]
    fn validate_rejects_cycle() {
        // 0 -> 1 -> 0 forms a cycle (both reference each other)
        let spec = WorkflowSpec::new(vec![
            WorkflowNode::new(task("a"), AgentRole::Plan).with_depends_on(vec![1]),
            WorkflowNode::new(task("b"), AgentRole::Plan).with_depends_on(vec![0]),
        ]);
        assert!(spec.validate().is_err());
    }

    #[test]
    fn tournament_node_requires_two_entrants() {
        // ≥2 entrants is valid; <2 is a spec error (no contest).
        let ok = WorkflowSpec::new(vec![WorkflowNode::new(task("rank"), AgentRole::Plan)
            .with_tournament(vec![task("a"), task("b")])]);
        ok.validate().unwrap();

        let one = WorkflowSpec::new(vec![WorkflowNode::new(task("rank"), AgentRole::Plan)
            .with_tournament(vec![task("only")])]);
        assert!(one.validate().is_err());
    }

    #[test]
    fn tournament_node_kind_round_trips_and_gates_dependents() {
        let spec = WorkflowSpec::new(vec![
            WorkflowNode::new(task("pick best"), AgentRole::Plan)
                .with_tournament(vec![task("x"), task("y"), task("z")]),
            WorkflowNode::new(task("use winner"), AgentRole::Implement).with_depends_on(vec![0]),
        ]);
        spec.validate().unwrap();
        // Only the controller is ready up front; the dependent waits for the bracket.
        assert_eq!(spec.to_task_graph().unwrap().ready_tasks(), vec![0]);
        // serde keeps the entrants under the tagged `tournament` kind.
        let json = serde_json::to_string(&spec.nodes[0].kind).unwrap();
        assert!(json.contains("\"type\":\"tournament\""), "{json}");
        let back: NodeKind = serde_json::from_str(&json).unwrap();
        assert_eq!(back, spec.nodes[0].kind);
    }

    #[test]
    fn node_builder_overrides_defaults() {
        let n = WorkflowNode::new(task("x"), AgentRole::Verify)
            .with_isolation(AgentIsolation::Worktree)
            .with_model_hint("opus");
        assert_eq!(n.isolation, AgentIsolation::Worktree);
        assert_eq!(n.model_hint.as_deref(), Some("opus"));
        // default inheritance for Verify is None (bias-resistant)
        assert_eq!(n.context_inheritance, ContextInheritance::None);
    }
}