feat(compile): formalize trigger filter IR with compile-time validation

Introduces a typed intermediate representation (IR) for trigger filter
expressions, replacing the manual bash string construction in pr_filters.rs.

The IR separates data acquisition (Fact) from boolean predicates (Predicate),
enabling:
- Compile-time conflict detection (impossible/redundant filter combinations)
- Dependency-ordered fact acquisition (pipeline vars → API → computed)
- A single codegen pass from IR → bash gate step
- Shared infrastructure for both PR and pipeline completion triggers

Filter compilation now follows a three-pass architecture:
1. Lower: PrFilters/PipelineFilters → Vec<FilterCheck>
2. Validate: detect conflicts (min>max, include/exclude overlap, zero-width
   time windows, label set contradictions)
3. Codegen: GateContext + Vec<FilterCheck> → bash gate step

Pipeline completion triggers now support runtime filters via gate steps
(GateContext::PipelineCompletion), using the same IR and codegen as PR filters.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

docs/extending.md

@@ -45,3 +45,30 @@ pub trait CompilerExtension: Send {
 ```
 
 To add a new runtime or tool: (1) create a directory under `src/tools/` or `src/runtimes/`, (2) implement `CompilerExtension` in `extension.rs`, (3) add a variant to the `Extension` enum and a collection check in `collect_extensions()` in `src/compile/extensions/mod.rs`.
+
+### Filter IR (`src/compile/filter_ir.rs`)
+
+Trigger filter expressions (PR filters, pipeline filters) are compiled to bash
+gate steps via a three-pass IR pipeline:
+
+1. **Lower** — `PrFilters` / `PipelineFilters` → `Vec<FilterCheck>` (typed
+   predicates over typed facts)
+2. **Validate** — detect conflicts at compile time (impossible combinations,
+   redundant checks)
+3. **Codegen** — dependency-ordered fact acquisition + predicate evaluation →
+   bash gate step
+
+To add a new filter type:
+
+1. **Add a `Fact` variant** (if the filter needs a new data source) — implement
+   `dependencies()`, `shell_var()`, `acquisition_bash()`, and
+   `failure_policy()` on the new variant
+2. **Add a `Predicate` variant** (if the filter needs a new test shape) —
+   implement the codegen match arm in `emit_predicate_check()`
+3. **Extend lowering** — add the filter field to `PrFilters` or
+   `PipelineFilters` in `types.rs`, then add the lowering logic in
+   `lower_pr_filters()` or `lower_pipeline_filters()` in `filter_ir.rs`
+4. **Add validation rules** — check for conflicts with other filters in
+   `validate_pr_filters()` or `validate_pipeline_filters()`
+5. **Write tests** — lowering test, validation test, and codegen test in
+   `filter_ir.rs`

docs/front-matter.md

@@ -71,13 +71,49 @@ safe-outputs:                  # optional per-tool configuration for safe output
     artifact-link:             # optional: link work item to repository branch
       enabled: true
       branch: main
-triggers:                      # optional pipeline triggers
+on:                            # trigger configuration (unified under on: key)
+  schedule: daily around 14:00 # fuzzy schedule - see docs/schedule-syntax.md
   pipeline:
     name: "Build Pipeline"     # source pipeline name
     project: "OtherProject"    # optional: project name if different
     branches:                  # optional: branches to trigger on
       - main
       - release/*
+    filters:                   # optional runtime filters (compiled to gate step)
+      source-pipeline:
+        match: "Build.*"
+      time-window:
+        start: "09:00"
+        end: "17:00"
+  pr:                          # PR trigger
+    branches:
+      include: [main]
+    paths:
+      include: [src/*]
+    filters:                   # runtime PR filters (compiled to gate step)
+      title:
+        match: "\\[review\\]"
+      author:
+        include: ["alice@corp.com"]
+      draft: false
+      labels:
+        any-of: ["run-agent"]
+      source-branch:
+        match: "^feature/.*"
+      target-branch:
+        match: "^main$"
+      commit-message:
+        match: "^(?!.*\\[skip-agent\\])"
+      changed-files:
+        include: ["src/**/*.rs"]
+      min-changes: 5
+      max-changes: 100
+      time-window:
+        start: "09:00"
+        end: "17:00"
+      build-reason:
+        include: [PullRequest]
+      expression: "eq(variables['Custom.Flag'], 'true')"  # raw ADO condition
 steps:                         # inline steps before agent runs (same job, generate context)
   - bash: echo "Preparing context for agent"
     displayName: "Prepare context"
@@ -127,3 +163,21 @@ list:
 
 Set `workspace:` explicitly to `root`, `repo` (alias `self`), or a specific
 checked-out repository alias to override this behavior.
+
+## Filter Validation
+
+The compiler validates filter configurations at compile time and will emit
+errors for impossible or conflicting combinations:
+
+| Condition | Severity | Message |
+|-----------|----------|---------|
+| `min-changes` > `max-changes` | Error | No PR can satisfy both constraints |
+| `time-window.start` = `time-window.end` | Error | Zero-width window never matches |
+| Same value in `author.include` and `author.exclude` | Error | Conflicting include/exclude |
+| Same value in `build-reason.include` and `build-reason.exclude` | Error | Conflicting include/exclude |
+| Label in both `labels.any-of` and `labels.none-of` | Error | Label both required and blocked |
+| Label in both `labels.all-of` and `labels.none-of` | Error | Label both required and blocked |
+| Empty `labels` filter (no any-of/all-of/none-of) | Warning | No label checks applied |
+
+Errors cause compilation to fail. Fix the conflicting filter configuration
+before recompiling.

src/compile/common.rs

@@ -1182,28 +1182,45 @@ pub fn validate_resolve_pr_thread_statuses(front_matter: &FrontMatter) -> Result
 /// Generate the setup job YAML.
 ///
 /// When `pr_filters` is `Some`, injects a pre-activation gate step that evaluates
-/// PR filters and self-cancels the build if they don't match. The Setup job is
-/// created even if `setup_steps` is empty (solely for the gate).
+/// PR filters and self-cancels the build if they don't match. When `pipeline_filters`
+/// is `Some`, injects a similar gate step for pipeline completion triggers.
+/// The Setup job is created even if `setup_steps` is empty (solely for the gate).
 pub fn generate_setup_job(
     setup_steps: &[serde_yaml::Value],
     pool: &str,
     pr_filters: Option<&super::types::PrFilters>,
+    pipeline_filters: Option<&super::types::PipelineFilters>,
 ) -> String {
-    if setup_steps.is_empty() && pr_filters.is_none() {
+    if setup_steps.is_empty() && pr_filters.is_none() && pipeline_filters.is_none() {
         return String::new();
     }
 
+    let has_gate = pr_filters.is_some() || pipeline_filters.is_some();
     let mut steps_parts = Vec::new();
 
-    // Gate step (if PR filters are configured)
+    // PR gate step
     if let Some(filters) = pr_filters {
         steps_parts.push(super::pr_filters::generate_pr_gate_step(filters));
     }
 
-    // User setup steps (conditioned on gate passing when PR filters are active)
+    // Pipeline gate step
+    if let Some(filters) = pipeline_filters {
+        steps_parts.push(generate_pipeline_gate_step(filters));
+    }
+
+    // User setup steps (conditioned on gate passing when filters are active)
     if !setup_steps.is_empty() {
-        if pr_filters.is_some() {
-            let conditioned = super::pr_filters::add_condition_to_steps(setup_steps, "eq(variables['prGate.SHOULD_RUN'], 'true')");
+        if has_gate {
+            // Determine which gate step name to reference
+            let gate_var = if pr_filters.is_some() {
+                "prGate.SHOULD_RUN"
+            } else {
+                "pipelineGate.SHOULD_RUN"
+            };
+            let conditioned = super::pr_filters::add_condition_to_steps(
+                setup_steps,
+                &format!("eq(variables['{gate_var}'], 'true')"),
+            );
             steps_parts.push(format_steps_yaml_indented(&conditioned, 4));
         } else {
             steps_parts.push(format_steps_yaml_indented(setup_steps, 4));
@@ -1225,6 +1242,34 @@ pub fn generate_setup_job(
     )
 }
 
+/// Generate a pipeline gate step using the filter IR.
+fn generate_pipeline_gate_step(filters: &super::types::PipelineFilters) -> String {
+    use super::filter_ir::{
+        compile_gate_step, lower_pipeline_filters, validate_pipeline_filters, GateContext,
+        Severity,
+    };
+
+    let diags = validate_pipeline_filters(filters);
+    for diag in &diags {
+        match diag.severity {
+            Severity::Error => eprintln!("error: {}", diag),
+            Severity::Warning => eprintln!("warning: {}", diag),
+            Severity::Info => eprintln!("info: {}", diag),
+        }
+    }
+    if diags.iter().any(|d| d.severity == Severity::Error) {
+        let errors: Vec<String> = diags
+            .iter()
+            .filter(|d| d.severity == Severity::Error)
+            .map(|d| format!("# FILTER ERROR: {}", d))
+            .collect();
+        return errors.join("\n");
+    }
+
+    let checks = lower_pipeline_filters(filters);
+    compile_gate_step(GateContext::PipelineCompletion, &checks)
+}
+
 /// Generate the teardown job YAML
 pub fn generate_teardown_job(
     teardown_steps: &[serde_yaml::Value],
@@ -1285,15 +1330,18 @@ pub fn generate_finalize_steps(finalize_steps: &[serde_yaml::Value]) -> String {
 
 /// Generate dependsOn clause and condition for setup/gate dependencies.
 ///
-/// When PR filters are active, adds a condition that allows non-PR builds to
-/// proceed unconditionally, while PR builds require the gate to pass.
+/// When PR or pipeline filters are active, adds a condition that allows
+/// non-matching trigger types to proceed unconditionally, while matching
+/// builds require the gate to pass.
 /// When `expression` is provided, it's ANDed into the condition as an escape hatch.
 pub fn generate_agentic_depends_on(
     setup_steps: &[serde_yaml::Value],
     has_pr_filters: bool,
+    has_pipeline_filters: bool,
     expression: Option<&str>,
 ) -> String {
-    let has_setup = !setup_steps.is_empty() || has_pr_filters;
+    let has_gate = has_pr_filters || has_pipeline_filters;
+    let has_setup = !setup_steps.is_empty() || has_gate;
 
     if !has_setup && expression.is_none() {
         return String::new();
@@ -1305,7 +1353,7 @@ pub fn generate_agentic_depends_on(
         ""
     };
 
-    if has_pr_filters || expression.is_some() {
+    if has_gate || expression.is_some() {
         let mut parts = Vec::new();
         parts.push("succeeded()".to_string());
 
@@ -1319,6 +1367,16 @@ pub fn generate_agentic_depends_on(
             );
         }
 
+        if has_pipeline_filters {
+            parts.push(
+                "or(\n\
+                 \x20         ne(variables['Build.Reason'], 'ResourceTrigger'),\n\
+                 \x20         eq(dependencies.Setup.outputs['pipelineGate.SHOULD_RUN'], 'true')\n\
+                 \x20       )"
+                    .to_string(),
+            );
+        }
+
         if let Some(expr) = expression {
             parts.push(expr.to_string());
         }
@@ -1954,7 +2012,9 @@ pub async fn compile_shared(
     // 8. Setup/teardown jobs, parameters, prepare/finalize steps
     let pr_filters = front_matter.pr_filters();
     let has_pr_filters = pr_filters.is_some();
-    let setup_job = generate_setup_job(&front_matter.setup, &pool, pr_filters);
+    let pipeline_filters = front_matter.pipeline_filters();
+    let has_pipeline_filters = pipeline_filters.is_some();
+    let setup_job = generate_setup_job(&front_matter.setup, &pool, pr_filters, pipeline_filters);
     let teardown_job = generate_teardown_job(&front_matter.teardown, &pool);
     let has_memory = front_matter
         .tools
@@ -1965,8 +2025,15 @@ pub async fn compile_shared(
     let parameters_yaml = generate_parameters(&parameters)?;
     let prepare_steps = generate_prepare_steps(&front_matter.steps, extensions)?;
     let finalize_steps = generate_finalize_steps(&front_matter.post_steps);
-    let expression = pr_filters.and_then(|f| f.expression.as_deref());
-    let agentic_depends_on = generate_agentic_depends_on(&front_matter.setup, has_pr_filters, expression);
+    let pr_expression = pr_filters.and_then(|f| f.expression.as_deref());
+    let pipeline_expression = pipeline_filters.and_then(|f| f.expression.as_deref());
+    let expression = pr_expression.or(pipeline_expression);
+    let agentic_depends_on = generate_agentic_depends_on(
+        &front_matter.setup,
+        has_pr_filters,
+        has_pipeline_filters,
+        expression,
+    );
     let job_timeout = generate_job_timeout(front_matter);
 
     // 9. Token acquisition and env vars