fix(compile): docs syntax, ADO expression injection, refs/heads stripping

Documentation fixes:
- front-matter.md: all PatternFilter examples updated to bare string
  glob syntax (was using removed {match: ...} object form + regex)
- filter-ir.md: all RegexMatch/regex_match references updated to
  GlobMatch/glob_match

Security:
- expression escape hatch now validated against ADO expressions
  via contains_ado_expression() — blocks macro injection

ADO branch prefix handling:
- gate-eval.py strips refs/heads/, refs/tags/, refs/pull/ from branch
  fact values so patterns like 'feature/*' match naturally
- Pattern side also stripped so 'refs/heads/feature/*' matches too
- 5 new Python tests for ref prefix stripping

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

Author: jamesadevine

docs/filter-ir.md

@@ -113,7 +113,7 @@ supports these predicate types:
 
 | Predicate | Bash Shape | Example |
 |-----------|-----------|---------|
-| `RegexMatch { fact, pattern }` | `echo "$VAR" \| grep -qE 'pattern'` | Title matches `\[review\]` |
+| `GlobMatch { fact, pattern }` | `fnmatch(value, pattern)` | Title matches `*[review]*` |
 | `Equality { fact, value }` | `[ "$VAR" = "value" ]` | Draft is `false` |
 | `ValueInSet { fact, values, case_insensitive }` | `echo "$VAR" \| grep -q[i]E '^(a\|b)$'` | Author in allow-list |
 | `ValueNotInSet { fact, values, case_insensitive }` | Inverse of `ValueInSet` | Author not in block-list |
@@ -169,12 +169,12 @@ Maps each field of `PrFilters` to a `FilterCheck`:
 
 | Field | Predicate | Fact(s) | Tag Suffix |
 |-------|-----------|---------|------------|
-| `title` | `RegexMatch` | `PrTitle` | `title-mismatch` |
+| `title` | `GlobMatch` | `PrTitle` | `title-mismatch` |
 | `author.include` | `ValueInSet` (case-insensitive) | `AuthorEmail` | `author-mismatch` |
 | `author.exclude` | `ValueNotInSet` (case-insensitive) | `AuthorEmail` | `author-excluded` |
-| `source_branch` | `RegexMatch` | `SourceBranch` | `source-branch-mismatch` |
-| `target_branch` | `RegexMatch` | `TargetBranch` | `target-branch-mismatch` |
-| `commit_message` | `RegexMatch` | `CommitMessage` | `commit-message-mismatch` |
+| `source_branch` | `GlobMatch` | `SourceBranch` | `source-branch-mismatch` |
+| `target_branch` | `GlobMatch` | `TargetBranch` | `target-branch-mismatch` |
+| `commit_message` | `GlobMatch` | `CommitMessage` | `commit-message-mismatch` |
 | `labels` | `LabelSetMatch` | `PrLabels` (→ `PrMetadata`) | `labels-mismatch` |
 | `draft` | `Equality` | `PrIsDraft` (→ `PrMetadata`) | `draft-mismatch` |
 | `changed_files` | `FileGlobMatch` | `ChangedFiles` | `changed-files-mismatch` |
@@ -187,8 +187,8 @@ Maps each field of `PrFilters` to a `FilterCheck`:
 
 | Field | Predicate | Fact(s) | Tag Suffix |
 |-------|-----------|---------|------------|
-| `source_pipeline` | `RegexMatch` | `TriggeredByPipeline` | `source-pipeline-mismatch` |
-| `branch` | `RegexMatch` | `TriggeringBranch` | `branch-mismatch` |
+| `source_pipeline` | `GlobMatch` | `TriggeredByPipeline` | `source-pipeline-mismatch` |
+| `branch` | `GlobMatch` | `TriggeringBranch` | `branch-mismatch` |
 | `time_window` | `TimeWindow` | `CurrentUtcMinutes` | `time-window-mismatch` |
 | `build_reason.include` | `ValueInSet` | `BuildReason` | `build-reason-mismatch` |
 | `build_reason.exclude` | `ValueNotInSet` | `BuildReason` | `build-reason-excluded` |
@@ -286,7 +286,7 @@ quoting issues. Decoded, it contains:
   "checks": [
     {
       "name": "title",
-      "predicate": {"type": "regex_match", "fact": "pr_title", "pattern": "\\[review\\]"},
+      "predicate": {"type": "glob_match", "fact": "pr_title", "pattern": "*[review]*"},
       "tag_suffix": "title-mismatch"
     },
     {
@@ -335,7 +335,7 @@ The bash shim exports only the ADO macros needed by the spec's facts:
 
 | `type` | Fields | Description |
 |--------|--------|-------------|
-| `regex_match` | `fact`, `pattern` | Python `re.search()` |
+| `glob_match` | `fact`, `pattern` | Glob match (`*` any chars, `?` single char) |
 | `equals` | `fact`, `value` | Exact string equality |
 | `value_in_set` | `fact`, `values`, `case_insensitive` | Value membership |
 | `value_not_in_set` | `fact`, `values`, `case_insensitive` | Inverse membership |
@@ -424,3 +424,4 @@ step-by-step guide. In summary:
    `lower_pipeline_filters`)
 6. Add validation rules if the new filter can conflict with existing ones
 7. Write tests: lowering, validation, spec serialization, and evaluator
+

docs/front-matter.md

@@ -80,8 +80,7 @@ on:                            # trigger configuration (unified under on: key)
       - main
       - release/*
     filters:                   # optional runtime filters (compiled to gate step)
-      source-pipeline:
-        match: "Build.*"
+      source-pipeline: "Build*"
       time-window:
         start: "09:00"
         end: "17:00"
@@ -91,19 +90,15 @@ on:                            # trigger configuration (unified under on: key)
     paths:
       include: [src/*]
     filters:                   # runtime PR filters (compiled to gate step)
-      title:
-        match: "\\[review\\]"
+      title: "*[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\\])"
+      source-branch: "feature/*"
+      target-branch: "main"
+      commit-message: "*[skip-agent]*"
       changed-files:
         include: ["src/**/*.rs"]
       min-changes: 5

scripts/gate-eval.py

@@ -19,6 +19,17 @@
     "changed_file_count": ["changed_files"],
 }
 
+# ADO branch variables return refs/heads/... or refs/pull/... prefixed values.
+# Strip the prefix so user patterns like "feature/*" match naturally.
+_REF_PREFIXES = ("refs/heads/", "refs/tags/", "refs/pull/")
+
+def _strip_ref_prefix(value):
+    """Strip refs/heads/ (or similar) prefix from a branch/ref value."""
+    for prefix in _REF_PREFIXES:
+        if value.startswith(prefix):
+            return value[len(prefix):]
+    return value
+
 # ─── Fact acquisition ────────────────────────────────────────────────────────
 
 def acquire_fact(kind, acquired):
@@ -35,7 +46,13 @@ def acquire_fact(kind, acquired):
         "triggering_branch": "ADO_TRIGGERING_BRANCH",
     }
     if kind in env_facts:
-        return os.environ.get(env_facts[kind], "")
+        value = os.environ.get(env_facts[kind], "")
+        # ADO branch variables include refs/heads/ prefix — strip it
+        # so user patterns like "feature/*" match without the prefix.
+        # Also strip from the pattern side in glob_match (below).
+        if kind in ("source_branch", "target_branch", "triggering_branch"):
+            value = _strip_ref_prefix(value)
+        return value
 
     if kind == "pr_metadata":
         return _fetch_pr_metadata()
@@ -125,7 +142,7 @@ def evaluate(pred, facts):
         # Simple glob: * matches anything, ? matches single char.
         # Brackets are NOT character classes (treated literally).
         import re as _re
-        pattern = pred["pattern"]
+        pattern = _strip_ref_prefix(pred["pattern"])
         # Escape everything except * and ?, then convert * → .* and ? → .
         regex = _re.escape(pattern).replace(r"\*", ".*").replace(r"\?", ".")
         return bool(_re.fullmatch(regex, value))

src/compile/common.rs

@@ -2019,6 +2019,13 @@ pub async fn compile_shared(
 
     // Validate expression escape hatches against injection
     for expr in &expressions {
+        if crate::validate::contains_ado_expression(expr) {
+            anyhow::bail!(
+                "Filter expression contains ADO expression ('${{{{', '$(', or '$[') which could \
+                 exfiltrate secrets or escalate permissions. Found: '{}'",
+                expr
+            );
+        }
         if crate::validate::contains_template_marker(expr) {
             anyhow::bail!(
                 "Filter expression contains template marker '{{{{' which could cause injection. Found: '{}'",

tests/gate_eval_tests.py

@@ -21,6 +21,30 @@
 
 evaluate = gate_eval.evaluate
 predicate_facts = gate_eval.predicate_facts
+_strip_ref_prefix = gate_eval._strip_ref_prefix
+
+
+# ─── Ref prefix stripping tests ─────────────────────────────────────────────
+
+
+class TestStripRefPrefix:
+    def test_refs_heads(self):
+        assert _strip_ref_prefix("refs/heads/feature/my-branch") == "feature/my-branch"
+
+    def test_refs_tags(self):
+        assert _strip_ref_prefix("refs/tags/v1.0.0") == "v1.0.0"
+
+    def test_refs_pull(self):
+        assert _strip_ref_prefix("refs/pull/42/merge") == "42/merge"
+
+    def test_no_prefix(self):
+        assert _strip_ref_prefix("main") == "main"
+
+    def test_pattern_stripping_in_glob(self):
+        """User patterns like refs/heads/feature/* should match feature/my-branch"""
+        pred = {"type": "glob_match", "fact": "source_branch", "pattern": "refs/heads/feature/*"}
+        facts = {"source_branch": "feature/my-branch"}
+        assert evaluate(pred, facts) is True
 
 
 # ─── Predicate evaluation tests ─────────────────────────────────────────────