feat: add DAG catalog and ready planning

Expose nested DAG links and execution hints so an external orchestrator can traverse the review/eval graphs and ask for the next runnable frontier instead of treating the contracts as static metadata.

Made-with: Cursor

Author: haasonsaas

src/commands/dag.rs

@@ -0,0 +1,82 @@
+use anyhow::Result;
+
+use crate::config;
+use crate::core::dag::{plan_dag_execution, DagCatalog, DagExecutionPlan, DagGraphContract};
+use crate::review::{describe_review_pipeline_graph, describe_review_postprocess_graph};
+
+use super::eval::describe_eval_fixture_graph;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum DagGraphSelection {
+    Review,
+    Postprocess { convention_store_path: bool },
+    Eval { repro_validate: bool },
+}
+
+pub(crate) fn describe_dag_graph(
+    config: &config::Config,
+    selection: DagGraphSelection,
+) -> DagGraphContract {
+    match selection {
+        DagGraphSelection::Review => describe_review_pipeline_graph(),
+        DagGraphSelection::Postprocess {
+            convention_store_path,
+        } => describe_review_postprocess_graph(config, convention_store_path),
+        DagGraphSelection::Eval { repro_validate } => describe_eval_fixture_graph(repro_validate),
+    }
+}
+
+pub(crate) fn build_dag_catalog(
+    config: &config::Config,
+    repro_validate: bool,
+    convention_store_path: bool,
+) -> DagCatalog {
+    DagCatalog {
+        graphs: vec![
+            describe_dag_graph(config, DagGraphSelection::Review),
+            describe_dag_graph(
+                config,
+                DagGraphSelection::Postprocess {
+                    convention_store_path,
+                },
+            ),
+            describe_dag_graph(config, DagGraphSelection::Eval { repro_validate }),
+        ],
+    }
+}
+
+pub(crate) fn plan_dag_graph(
+    config: &config::Config,
+    selection: DagGraphSelection,
+    completed: &[String],
+) -> Result<DagExecutionPlan> {
+    let graph = describe_dag_graph(config, selection);
+    plan_dag_execution(&graph, completed)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn dag_catalog_includes_nested_eval_and_review_graphs() {
+        let catalog = build_dag_catalog(&config::Config::default(), true, true);
+
+        assert_eq!(catalog.graphs.len(), 3);
+        assert_eq!(catalog.graphs[0].name, "review_pipeline");
+        assert_eq!(catalog.graphs[1].name, "review_postprocess");
+        assert_eq!(catalog.graphs[2].name, "eval_fixture_execution");
+    }
+
+    #[test]
+    fn dag_planner_reports_ready_nodes_for_review_pipeline() {
+        let plan = plan_dag_graph(
+            &config::Config::default(),
+            DagGraphSelection::Review,
+            &["initialize_services".to_string()],
+        )
+        .unwrap();
+
+        assert_eq!(plan.ready, vec!["build_session"]);
+    }
+}

src/commands/eval/runner/execute/dag.rs

@@ -5,7 +5,8 @@ use tracing::debug;
 use crate::config;
 use crate::core;
 use crate::core::dag::{
-    describe_dag, execute_dag, DagGraphContract, DagNode, DagNodeContract, DagNodeKind, DagNodeSpec,
+    describe_dag, execute_dag, DagGraphContract, DagNode, DagNodeContract, DagNodeExecutionHints,
+    DagNodeKind, DagNodeSpec,
 };
 use crate::core::eval_benchmarks::FixtureResult as BenchmarkFixtureResult;
 use crate::review::review_diff_content_raw;
@@ -153,6 +154,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     "verification_report".to_string(),
                     "agent_activity".to_string(),
                 ],
+                hints: DagNodeExecutionHints {
+                    parallelizable: false,
+                    retryable: true,
+                    side_effects: false,
+                    subgraph: Some("review_pipeline".to_string()),
+                },
                 enabled: spec.enabled,
             },
             EvalFixtureStage::ExpectationMatching => DagNodeContract {
@@ -168,6 +175,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     .collect(),
                 inputs: vec!["comments".to_string(), "fixture_expectations".to_string()],
                 outputs: vec!["match_summary".to_string(), "failures".to_string()],
+                hints: DagNodeExecutionHints {
+                    parallelizable: true,
+                    retryable: true,
+                    side_effects: false,
+                    subgraph: None,
+                },
                 enabled: spec.enabled,
             },
             EvalFixtureStage::CommentCountValidation => DagNodeContract {
@@ -186,6 +199,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     "failures".to_string(),
                 ],
                 outputs: vec!["failures".to_string()],
+                hints: DagNodeExecutionHints {
+                    parallelizable: true,
+                    retryable: true,
+                    side_effects: false,
+                    subgraph: None,
+                },
                 enabled: spec.enabled,
             },
             EvalFixtureStage::BenchmarkMetrics => DagNodeContract {
@@ -205,6 +224,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     "failures".to_string(),
                 ],
                 outputs: vec!["benchmark_metrics".to_string()],
+                hints: DagNodeExecutionHints {
+                    parallelizable: true,
+                    retryable: true,
+                    side_effects: false,
+                    subgraph: None,
+                },
                 enabled: spec.enabled,
             },
             EvalFixtureStage::ReproductionValidation => DagNodeContract {
@@ -224,6 +249,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     "comments".to_string(),
                 ],
                 outputs: vec!["reproduction_summary".to_string(), "warnings".to_string()],
+                hints: DagNodeExecutionHints {
+                    parallelizable: false,
+                    retryable: true,
+                    side_effects: false,
+                    subgraph: None,
+                },
                 enabled: spec.enabled,
             },
             EvalFixtureStage::ArtifactCapture => DagNodeContract {
@@ -245,6 +276,12 @@ pub(in super::super::super) fn describe_eval_fixture_graph(
                     "benchmark_metrics".to_string(),
                 ],
                 outputs: vec!["artifact_path".to_string()],
+                hints: DagNodeExecutionHints {
+                    parallelizable: false,
+                    retryable: true,
+                    side_effects: true,
+                    subgraph: None,
+                },
                 enabled: spec.enabled,
             },
         })
@@ -462,6 +499,9 @@ mod tests {
 
         assert_eq!(graph.name, "eval_fixture_execution");
         assert_eq!(graph.entry_nodes, vec!["review"]);
+        assert!(graph.nodes.iter().any(|node| {
+            node.name == "review" && node.hints.subgraph.as_deref() == Some("review_pipeline")
+        }));
         assert!(graph.nodes.iter().any(|node| {
             node.name == "reproduction_validation"
                 && node.outputs.contains(&"reproduction_summary".to_string())

src/commands/mod.rs

@@ -1,3 +1,4 @@
+mod dag;
 mod doctor;
 mod eval;
 mod feedback_eval;
@@ -7,8 +8,8 @@ mod pr;
 mod review;
 mod smart_review;
 
+pub(crate) use dag::{build_dag_catalog, describe_dag_graph, plan_dag_graph, DagGraphSelection};
 pub use doctor::doctor_command;
-pub(crate) use eval::describe_eval_fixture_graph;
 pub use eval::{eval_command, EvalRunOptions};
 pub use feedback_eval::feedback_eval_command;
 pub use git::{git_command, GitCommands};

src/core/dag.rs

@@ -43,6 +43,7 @@ pub struct DagNodeContract {
     pub dependencies: Vec<String>,
     pub inputs: Vec<String>,
     pub outputs: Vec<String>,
+    pub hints: DagNodeExecutionHints,
     pub enabled: bool,
 }
 
@@ -55,6 +56,37 @@ pub struct DagGraphContract {
     pub nodes: Vec<DagNodeContract>,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DagNodeExecutionHints {
+    pub parallelizable: bool,
+    pub retryable: bool,
+    pub side_effects: bool,
+    pub subgraph: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DagCatalog {
+    pub graphs: Vec<DagGraphContract>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DagNodePlanState {
+    pub name: String,
+    pub enabled: bool,
+    pub completed: bool,
+    pub ready: bool,
+    pub unmet_dependencies: Vec<String>,
+    pub subgraph: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DagExecutionPlan {
+    pub graph_name: String,
+    pub completed: Vec<String>,
+    pub ready: Vec<String>,
+    pub nodes: Vec<DagNodePlanState>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DagExecutionRecord {
     pub name: String,
@@ -123,6 +155,50 @@ where
     Ok(records)
 }
 
+pub fn plan_dag_execution(
+    graph: &DagGraphContract,
+    completed: &[String],
+) -> Result<DagExecutionPlan> {
+    let completed_set = completed.iter().cloned().collect::<HashSet<_>>();
+
+    for name in &completed_set {
+        if !graph.nodes.iter().any(|node| node.name == *name) {
+            anyhow::bail!("Unknown completed node '{}' for DAG '{}'", name, graph.name);
+        }
+    }
+
+    let mut ready = Vec::new();
+    let mut nodes = Vec::with_capacity(graph.nodes.len());
+    for node in &graph.nodes {
+        let unmet_dependencies = node
+            .dependencies
+            .iter()
+            .filter(|dependency| !completed_set.contains(*dependency))
+            .cloned()
+            .collect::<Vec<_>>();
+        let is_completed = completed_set.contains(&node.name);
+        let is_ready = node.enabled && !is_completed && unmet_dependencies.is_empty();
+        if is_ready {
+            ready.push(node.name.clone());
+        }
+        nodes.push(DagNodePlanState {
+            name: node.name.clone(),
+            enabled: node.enabled,
+            completed: is_completed,
+            ready: is_ready,
+            unmet_dependencies,
+            subgraph: node.hints.subgraph.clone(),
+        });
+    }
+
+    Ok(DagExecutionPlan {
+        graph_name: graph.name.clone(),
+        completed: completed.to_vec(),
+        ready,
+        nodes,
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -199,4 +275,52 @@ mod tests {
         assert_eq!(descriptions[1].dependencies, vec!["root"]);
         assert!(!descriptions[1].enabled);
     }
+
+    #[test]
+    fn plan_dag_execution_marks_ready_nodes() {
+        let graph = DagGraphContract {
+            name: "test".to_string(),
+            description: "test graph".to_string(),
+            entry_nodes: vec!["root".to_string()],
+            terminal_nodes: vec!["leaf".to_string()],
+            nodes: vec![
+                DagNodeContract {
+                    name: "root".to_string(),
+                    description: "root".to_string(),
+                    kind: DagNodeKind::Setup,
+                    dependencies: vec![],
+                    inputs: vec![],
+                    outputs: vec![],
+                    hints: DagNodeExecutionHints {
+                        parallelizable: false,
+                        retryable: true,
+                        side_effects: false,
+                        subgraph: None,
+                    },
+                    enabled: true,
+                },
+                DagNodeContract {
+                    name: "leaf".to_string(),
+                    description: "leaf".to_string(),
+                    kind: DagNodeKind::Execution,
+                    dependencies: vec!["root".to_string()],
+                    inputs: vec![],
+                    outputs: vec![],
+                    hints: DagNodeExecutionHints {
+                        parallelizable: true,
+                        retryable: true,
+                        side_effects: false,
+                        subgraph: Some("child".to_string()),
+                    },
+                    enabled: true,
+                },
+            ],
+        };
+
+        let plan = plan_dag_execution(&graph, &["root".to_string()]).unwrap();
+
+        assert_eq!(plan.ready, vec!["leaf"]);
+        assert!(plan.nodes[0].completed);
+        assert_eq!(plan.nodes[1].subgraph.as_deref(), Some("child"));
+    }
 }