feat(engine): implement unified variable resolver with rule-based transformation pipeline

BREAKING CHANGE: Replace legacy VariableResolver with new architecture that provides:
- Expression classification for optimal Jinja2 routing
- Rule-based transformation pipeline (security, syntax, namespace)
- Enhanced context with BlockProxy and SecretProxy
- SandboxedEnvironment for template rendering security
- Clean separation of concerns between rules and evaluation

Key components:
- UnifiedVariableResolver: Main resolver orchestrating transformation pipeline
- ExpressionClassifier: Routes expressions to appropriate evaluation methods
- TransformRule system: Modular, priority-based transformation rules
- BlockProxy: ADR-007 shortcuts and nested block access
- SecretProxy: Lazy secret loading with audit logging
- Security rules: Forbidden namespace blocking, secret tracking
- Syntax rules: Bracket notation normalization, special character handling

Updates:
- RenderTemplateExecutor uses SandboxedEnvironment instead of Environment
- BlockOrchestrator switches to UnifiedVariableResolver
- Legacy variables.py preserved as variables.py.bak
- Test workflows and snapshots reorganized for new resolver

Author: ibacalu

src/workflows_mcp/engine/executors_file.py

@@ -15,7 +15,8 @@
 from typing import Any, ClassVar, Literal
 
 import yaml
-from jinja2 import Environment, StrictUndefined
+from jinja2 import StrictUndefined
+from jinja2.sandbox import SandboxedEnvironment
 from pydantic import BaseModel, Field, computed_field, field_validator
 
 from .block import BlockInput, BlockOutput
@@ -643,7 +644,7 @@ async def execute(  # type: ignore[override]
         create_parents = resolve_interpolatable_boolean(inputs.create_parents, "create_parents")
 
         # RenderTemplate template (exceptions bubble up)
-        env = Environment(undefined=StrictUndefined, autoescape=False)
+        env = SandboxedEnvironment(undefined=StrictUndefined, autoescape=False)
         template = env.from_string(inputs.template)
         rendered = template.render(**inputs.variables)
 

src/workflows_mcp/engine/orchestrator.py

@@ -403,7 +403,7 @@ async def execute_for_each(
               Metadata.create_for_each_parent()
             - Handles continue_on_error: false (fail-fast) and true (resilient)
         """
-        from .variables import VariableResolver
+        from .resolver import UnifiedVariableResolver
 
         # Validate iteration keys (ADR-009: security & stability)
         validate_iteration_keys(iterations)
@@ -430,7 +430,7 @@ async def execute_iteration(
             iteration_context_dict["each"] = each_context
 
             # Resolve iteration inputs (replace {{each.*}} variables)
-            resolver = VariableResolver(
+            resolver = UnifiedVariableResolver(
                 iteration_context_dict, secret_provider=self.secret_provider
             )
             resolved_inputs = await resolver.resolve_async(inputs_template)

src/workflows_mcp/engine/resolver/__init__.py

@@ -0,0 +1,38 @@
+"""
+Unified variable resolver package.
+
+This package implements a unified variable resolution system that combines
+workflow-specific domain rules with Jinja2's powerful expression evaluation.
+
+The architecture uses a clean overlay pattern with rule-based transformations:
+1. Expression classification for optimal routing
+2. Rule-based transformation pipeline
+3. Context enhancement with proxies
+4. Jinja2 evaluation with appropriate method
+5. Post-processing and validation
+
+Public API:
+    - UnifiedVariableResolver: Main resolver class for all variable resolution
+    - TransformRule: Base class for custom transformation rules
+    - BlockProxy: Proxy for block attribute shortcuts
+    - ExpressionClassifier: Expression type detection for routing
+"""
+
+from .classifier import ExpressionClassifier, ExpressionType
+from .proxies import BlockProxy, ProxyBase, SecretProxy
+from .rules import RuleContext, RuleType, TransformRule
+from .security_rules import SecurityError
+from .unified_resolver import UnifiedVariableResolver
+
+__all__ = [
+    "UnifiedVariableResolver",
+    "TransformRule",
+    "RuleType",
+    "RuleContext",
+    "BlockProxy",
+    "SecretProxy",
+    "ProxyBase",
+    "ExpressionClassifier",
+    "ExpressionType",
+    "SecurityError",
+]

src/workflows_mcp/engine/resolver/classifier.py

@@ -0,0 +1,153 @@
+"""
+Expression classification for optimal routing.
+
+This module classifies expressions to determine the most efficient evaluation
+strategy. Different expression types are routed to different Jinja2 methods:
+    - Pure variables: compile_expression (preserves types)
+    - Templates: from_string (always returns string)
+    - Complex expressions: compile_expression (full evaluation)
+
+Expression Types:
+    LITERAL: No template markers ({{...}})
+    PURE_VARIABLE: Single variable reference
+    FILTER_EXPRESSION: Variable with filter(s)
+    BOOLEAN_EXPRESSION: Boolean logic (and, or, not)
+    MATH_EXPRESSION: Mathematical operations
+    TEMPLATE: Mixed text and variables
+    COMPLEX_EXPRESSION: Function calls, parentheses, etc.
+"""
+
+import re
+from enum import Enum
+
+
+class ExpressionType(Enum):
+    """Types of expressions for optimal routing."""
+
+    LITERAL = "literal"  # No {{}} markers
+    PURE_VARIABLE = "pure_variable"  # {{blocks.foo}}
+    FILTER_EXPRESSION = "filter"  # {{value | default('x')}}
+    BOOLEAN_EXPRESSION = "boolean"  # {{a > 10 and b < 5}}
+    MATH_EXPRESSION = "math"  # {{(a * 2) + b}}
+    TEMPLATE = "template"  # Mixed text and {{}}
+    COMPLEX_EXPRESSION = "complex"  # Combination of above
+
+
+class ExpressionClassifier:
+    """
+    Classify expressions to route to appropriate handlers.
+
+    Classification Process:
+    1. Check for template markers ({{...}})
+    2. If single expression, analyze inner content
+    3. Route based on expression type
+
+    Example:
+        classifier = ExpressionClassifier()
+        expr_type = classifier.classify("{{blocks.foo.succeeded}}")
+        # Returns: ExpressionType.PURE_VARIABLE
+    """
+
+    # Regex patterns for classification
+    VARIABLE_PATTERN = re.compile(r"^[a-zA-Z_][\w\.\[\]\'\"]*$")
+    FILTER_PATTERN = re.compile(r"\s*\|")
+    BOOLEAN_OPS = {"and", "or", "not", "==", "!=", ">", "<", ">=", "<=", "is", "in"}
+    MATH_OPS = {"+", "-", "*", "/", "//", "%", "**"}
+
+    def classify(self, expression: str) -> ExpressionType:
+        """
+        Classify expression type for optimal handling.
+
+        Args:
+            expression: Expression string to classify
+
+        Returns:
+            ExpressionType enum value
+        """
+        # No template markers
+        if "{{" not in expression or "}}" not in expression:
+            return ExpressionType.LITERAL
+
+        # Check if pure expression (single {{...}})
+        stripped = expression.strip()
+        if stripped.startswith("{{") and stripped.endswith("}}"):
+            if stripped.count("{{") == 1 and stripped.count("}}") == 1:
+                # Extract inner expression
+                inner = stripped[2:-2].strip()
+                return self._classify_inner(inner)
+
+        # Multiple {{}} or mixed with text
+        return ExpressionType.TEMPLATE
+
+    def _classify_inner(self, inner: str) -> ExpressionType:
+        """
+        Classify the inner content of {{...}}.
+
+        Args:
+            inner: Inner expression content (without {{...}})
+
+        Returns:
+            ExpressionType enum value
+        """
+        # Has filter pipe
+        if "|" in inner:
+            return ExpressionType.FILTER_EXPRESSION
+
+        # Has boolean operators
+        tokens = self._tokenize(inner)
+        if any(op in tokens for op in self.BOOLEAN_OPS):
+            return ExpressionType.BOOLEAN_EXPRESSION
+
+        # Has math operators (but not inside strings)
+        if any(op in inner for op in self.MATH_OPS):
+            # Check if operators are inside string literals
+            if not self._is_inside_string(inner):
+                return ExpressionType.MATH_EXPRESSION
+
+        # Has parentheses (function call or grouping)
+        if "(" in inner and ")" in inner:
+            return ExpressionType.COMPLEX_EXPRESSION
+
+        # Simple variable reference
+        if self.VARIABLE_PATTERN.match(inner):
+            return ExpressionType.PURE_VARIABLE
+
+        # Default to complex
+        return ExpressionType.COMPLEX_EXPRESSION
+
+    def _tokenize(self, expr: str) -> list[str]:
+        """
+        Simple tokenization for operator detection.
+
+        Args:
+            expr: Expression to tokenize
+
+        Returns:
+            List of tokens
+        """
+        # Split on word boundaries while preserving operators
+        tokens = re.findall(r"\w+|[<>=!]+|\S", expr)
+        return tokens
+
+    def _is_inside_string(self, expr: str) -> bool:
+        """
+        Check if operators appear inside string literals.
+
+        This is a simplified check. Real implementation would need
+        proper string parsing with escape sequence handling.
+
+        Args:
+            expr: Expression to check
+
+        Returns:
+            True if expression appears to be inside strings
+        """
+        # Count quotes to detect if we're inside strings
+        # This is simplified - just checks if there are balanced quotes
+        single_quotes = expr.count("'") - expr.count("\\'")
+        double_quotes = expr.count('"') - expr.count('\\"')
+
+        # If we have balanced quotes, operators might be inside
+        return (single_quotes % 2 == 0 and single_quotes > 0) or (
+            double_quotes % 2 == 0 and double_quotes > 0
+        )