tasktree 0.0.20__py3-none-any.whl → 0.0.22__py3-none-any.whl

tasktree/parser.py

@@ -1,4 +1,7 @@
-"""Parse recipe YAML files and handle imports."""
+"""
+Parse recipe YAML files and handle imports.
+@athena: ec0087b16df9
+"""
 
 from __future__ import annotations
 
@@ -16,22 +19,30 @@ from tasktree.types import get_click_type
 
 
 class CircularImportError(Exception):
-    """Raised when a circular import is detected."""
+    """
+    Raised when a circular import is detected.
+    @athena: 935d53bc7d05
+    """
+
     pass
 
 
 @dataclass
 class Environment:
-    """Represents an execution environment configuration.
+    """
+    Represents an execution environment configuration.
 
     Can be either a shell environment or a Docker environment:
     - Shell environment: has 'shell' field, executes directly on host
     - Docker environment: has 'dockerfile' field, executes in container
+    @athena: cfe3f8754968
     """
 
     name: str
     shell: str = ""  # Path to shell (required for shell envs, optional for Docker)
-    args: list[str] | dict[str, str] = field(default_factory=list)  # Shell args (list) or Docker build args (dict)
+    args: list[str] | dict[str, str] = field(
+        default_factory=list
+    )  # Shell args (list) or Docker build args (dict)
     preamble: str = ""
     # Docker-specific fields (presence of dockerfile indicates Docker environment)
     dockerfile: str = ""  # Path to Dockerfile
@@ -40,41 +51,76 @@ class Environment:
     ports: list[str] = field(default_factory=list)  # Port mappings
     env_vars: dict[str, str] = field(default_factory=dict)  # Environment variables
     working_dir: str = ""  # Working directory (container or host)
-    extra_args: List[str] = field(default_factory=list) # Any extra arguments to pass to docker
+    extra_args: List[str] = field(
+        default_factory=list
+    )  # Any extra arguments to pass to docker
     run_as_root: bool = False  # If True, skip user mapping (run as root in container)
 
     def __post_init__(self):
-        """Ensure args is in the correct format."""
+        """
+        Ensure args is in the correct format.
+        @athena: a4292f3f4150
+        """
         if isinstance(self.args, str):
             self.args = [self.args]
 
 
 @dataclass
 class Task:
-    """Represents a task definition."""
+    """
+    Represents a task definition.
+    @athena: f516b5ae61c5
+    """
 
     name: str
     cmd: str
     desc: str = ""
-    deps: list[str | dict[str, Any]] = field(default_factory=list)  # Can be strings or dicts with args
-    inputs: list[str | dict[str, str]] = field(default_factory=list)  # Can be strings or dicts with named inputs
-    outputs: list[str | dict[str, str]] = field(default_factory=list)  # Can be strings or dicts with named outputs
+    deps: list[str | dict[str, Any]] = field(
+        default_factory=list
+    )  # Can be strings or dicts with args
+    inputs: list[str | dict[str, str]] = field(
+        default_factory=list
+    )  # Can be strings or dicts with named inputs
+    outputs: list[str | dict[str, str]] = field(
+        default_factory=list
+    )  # Can be strings or dicts with named outputs
     working_dir: str = ""
-    args: list[str | dict[str, Any]] = field(default_factory=list)  # Can be strings or dicts (each dict has single key: arg name)
+    args: list[str | dict[str, Any]] = field(
+        default_factory=list
+    )  # Can be strings or dicts (each dict has single key: arg name)
     source_file: str = ""  # Track which file defined this task
     env: str = ""  # Environment name to use for execution
     private: bool = False  # If True, task is hidden from --list output
 
     # Internal fields for efficient output lookup (built in __post_init__)
-    _output_map: dict[str, str] = field(init=False, default_factory=dict, repr=False)  # name → path mapping
-    _anonymous_outputs: list[str] = field(init=False, default_factory=list, repr=False)  # unnamed outputs
+    _output_map: dict[str, str] = field(
+        init=False, default_factory=dict, repr=False
+    )  # name → path mapping
+    _anonymous_outputs: list[str] = field(
+        init=False, default_factory=list, repr=False
+    )  # unnamed outputs
 
     # Internal fields for efficient input lookup (built in __post_init__)
-    _input_map: dict[str, str] = field(init=False, default_factory=dict, repr=False)  # name → path mapping
-    _anonymous_inputs: list[str] = field(init=False, default_factory=list, repr=False)  # unnamed inputs
+    _input_map: dict[str, str] = field(
+        init=False, default_factory=dict, repr=False
+    )  # name → path mapping
+    _anonymous_inputs: list[str] = field(
+        init=False, default_factory=list, repr=False
+    )  # unnamed inputs
+
+    # Internal fields for positional input/output access (built in __post_init__)
+    _indexed_inputs: list[str] = field(
+        init=False, default_factory=list, repr=False
+    )  # all inputs in YAML order
+    _indexed_outputs: list[str] = field(
+        init=False, default_factory=list, repr=False
+    )  # all outputs in YAML order
 
     def __post_init__(self):
-        """Ensure lists are always lists and build output maps."""
+        """
+        Ensure lists are always lists and build input/output maps and indexed lists.
+        @athena: a48b1eba81cd
+        """
         if isinstance(self.deps, str):
             self.deps = [self.deps]
         if isinstance(self.inputs, str):
@@ -100,6 +146,7 @@ class Task:
         # Build output maps for efficient lookup
         self._output_map = {}
         self._anonymous_outputs = []
+        self._indexed_outputs = []
 
         for idx, output in enumerate(self.outputs):
             if isinstance(output, dict):
@@ -116,7 +163,7 @@ class Task:
                         f"Task '{self.name}': Named output '{name}' must have a string path, got {type(path).__name__}: {path}"
                     )
 
-                if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', name):
+                if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
                     raise ValueError(
                         f"Task '{self.name}': Named output '{name}' must be a valid identifier "
                         f"(letters, numbers, underscores, cannot start with number)"
@@ -128,9 +175,11 @@ class Task:
                     )
 
                 self._output_map[name] = path
+                self._indexed_outputs.append(path)
             elif isinstance(output, str):
                 # Anonymous output: just store
                 self._anonymous_outputs.append(output)
+                self._indexed_outputs.append(output)
             else:
                 raise ValueError(
                     f"Task '{self.name}': Output at index {idx} must be a string or dict, got {type(output).__name__}: {output}"
@@ -139,6 +188,7 @@ class Task:
         # Build input maps for efficient lookup
         self._input_map = {}
         self._anonymous_inputs = []
+        self._indexed_inputs = []
 
         for idx, input_item in enumerate(self.inputs):
             if isinstance(input_item, dict):
@@ -155,7 +205,7 @@ class Task:
                         f"Task '{self.name}': Named input '{name}' must have a string path, got {type(path).__name__}: {path}"
                     )
 
-                if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', name):
+                if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
                     raise ValueError(
                         f"Task '{self.name}': Named input '{name}' must be a valid identifier "
                         f"(letters, numbers, underscores, cannot start with number)"
@@ -167,9 +217,11 @@ class Task:
                     )
 
                 self._input_map[name] = path
+                self._indexed_inputs.append(path)
             elif isinstance(input_item, str):
                 # Anonymous input: just store
                 self._anonymous_inputs.append(input_item)
+                self._indexed_inputs.append(input_item)
             else:
                 raise ValueError(
                     f"Task '{self.name}': Input at index {idx} must be a string or dict, got {type(input_item).__name__}: {input_item}"
@@ -178,23 +230,29 @@ class Task:
 
 @dataclass
 class DependencySpec:
-    """Parsed dependency specification with potential template placeholders.
+    """
+    Parsed dependency specification with potential template placeholders.
 
     This represents a dependency as defined in the recipe file, before template
     substitution. Argument values may contain {{ arg.* }} templates that will be
     substituted with parent task's argument values during graph construction.
 
     Attributes:
-        task_name: Name of the dependency task
-        arg_templates: Dictionary mapping argument names to string templates
-                      (None if no args specified). All values are strings, even
-                      for numeric types, to preserve template placeholders.
+    task_name: Name of the dependency task
+    arg_templates: Dictionary mapping argument names to string templates
+    (None if no args specified). All values are strings, even
+    for numeric types, to preserve template placeholders.
+    @athena: 7b2f8a15d312
     """
+
     task_name: str
     arg_templates: dict[str, str] | None = None
 
     def __str__(self) -> str:
-        """String representation for display."""
+        """
+        String representation for display.
+        @athena: e5669be6329b
+        """
         if not self.arg_templates:
             return self.task_name
         args_str = ", ".join(f"{k}={v}" for k, v in self.arg_templates.items())
@@ -203,17 +261,23 @@ class DependencySpec:
 
 @dataclass
 class DependencyInvocation:
-    """Represents a task dependency invocation with optional arguments.
+    """
+    Represents a task dependency invocation with optional arguments.
 
     Attributes:
-        task_name: Name of the dependency task
-        args: Dictionary of argument names to values (None if no args specified)
+    task_name: Name of the dependency task
+    args: Dictionary of argument names to values (None if no args specified)
+    @athena: 0c023366160b
     """
+
     task_name: str
     args: dict[str, Any] | None = None
 
     def __str__(self) -> str:
-        """String representation for display."""
+        """
+        String representation for display.
+        @athena: 22fc0502192b
+        """
         if not self.args:
             return self.task_name
         args_str = ", ".join(f"{k}={v}" for k, v in self.args.items())
@@ -222,17 +286,20 @@ class DependencyInvocation:
 
 @dataclass
 class ArgSpec:
-    """Represents a parsed argument specification.
+    """
+    Represents a parsed argument specification.
 
     Attributes:
-        name: Argument name
-        arg_type: Type of the argument (str, int, float, bool, path)
-        default: Default value as a string (None if no default)
-        is_exported: Whether the argument is exported as an environment variable
-        min_val: Minimum value for numeric arguments (None if not specified)
-        max_val: Maximum value for numeric arguments (None if not specified)
-        choices: List of valid choices for the argument (None if not specified)
+    name: Argument name
+    arg_type: Type of the argument (str, int, float, bool, path)
+    default: Default value as a string (None if no default)
+    is_exported: Whether the argument is exported as an environment variable
+    min_val: Minimum value for numeric arguments (None if not specified)
+    max_val: Maximum value for numeric arguments (None if not specified)
+    choices: List of valid choices for the argument (None if not specified)
+    @athena: fcaf20fb1ca2
     """
+
     name: str
     arg_type: str
     default: str | None = None
@@ -244,7 +311,10 @@ class ArgSpec:
 
 @dataclass
 class Recipe:
-    """Represents a parsed recipe file with all tasks."""
+    """
+    Represents a parsed recipe file with all tasks.
+    @athena: 47f568c77013
+    """
 
     tasks: dict[str, Task]
     project_root: Path
@@ -252,40 +322,56 @@ class Recipe:
     environments: dict[str, Environment] = field(default_factory=dict)
     default_env: str = ""  # Name of default environment
     global_env_override: str = ""  # Global environment override (set via CLI --env)
-    variables: dict[str, str] = field(default_factory=dict)  # Global variables (resolved at parse time) - DEPRECATED, use evaluated_variables
-    raw_variables: dict[str, Any] = field(default_factory=dict)  # Raw variable specs from YAML (not yet evaluated)
-    evaluated_variables: dict[str, str] = field(default_factory=dict)  # Evaluated variable values (cached after evaluation)
+    variables: dict[str, str] = field(
+        default_factory=dict
+    )  # Global variables (resolved at parse time) - DEPRECATED, use evaluated_variables
+    raw_variables: dict[str, Any] = field(
+        default_factory=dict
+    )  # Raw variable specs from YAML (not yet evaluated)
+    evaluated_variables: dict[str, str] = field(
+        default_factory=dict
+    )  # Evaluated variable values (cached after evaluation)
     _variables_evaluated: bool = False  # Track if variables have been evaluated
-    _original_yaml_data: dict[str, Any] = field(default_factory=dict)  # Store original YAML data for lazy evaluation context
+    _original_yaml_data: dict[str, Any] = field(
+        default_factory=dict
+    )  # Store original YAML data for lazy evaluation context
 
     def get_task(self, name: str) -> Task | None:
-        """Get task by name.
+        """
+        Get task by name.
 
         Args:
-            name: Task name (may be namespaced like 'build.compile')
+        name: Task name (may be namespaced like 'build.compile')
 
         Returns:
-            Task if found, None otherwise
+        Task if found, None otherwise
+        @athena: 3f8137d71757
         """
         return self.tasks.get(name)
 
     def task_names(self) -> list[str]:
-        """Get all task names."""
+        """
+        Get all task names.
+        @athena: 1df54563a7b6
+        """
         return list(self.tasks.keys())
 
     def get_environment(self, name: str) -> Environment | None:
-        """Get environment by name.
+        """
+        Get environment by name.
 
         Args:
-            name: Environment name
+        name: Environment name
 
         Returns:
-            Environment if found, None otherwise
+        Environment if found, None otherwise
+        @athena: 098227ca38a2
         """
         return self.environments.get(name)
 
     def evaluate_variables(self, root_task: str | None = None) -> None:
-        """Evaluate variables lazily based on task reachability.
+        """
+        Evaluate variables lazily based on task reachability.
 
         This method implements lazy variable evaluation, which only evaluates
         variables that are actually reachable from the target task. This provides:
@@ -299,15 +385,16 @@ class Recipe:
         This method is idempotent - calling it multiple times is safe (uses caching).
 
         Args:
-            root_task: Optional task name to determine reachability (None = evaluate all)
+        root_task: Optional task name to determine reachability (None = evaluate all)
 
         Raises:
-            ValueError: If variable evaluation or substitution fails
+        ValueError: If variable evaluation or substitution fails
 
         Example:
-            >>> recipe = parse_recipe(path)  # Variables not yet evaluated
-            >>> recipe.evaluate_variables("build")  # Evaluate only reachable variables
-            >>> # Now recipe.evaluated_variables contains only vars used by "build" task
+        >>> recipe = parse_recipe(path)  # Variables not yet evaluated
+        >>> recipe.evaluate_variables("build")  # Evaluate only reachable variables
+        >>> # Now recipe.evaluated_variables contains only vars used by "build" task
+        @athena: d8de7b5f42b6
         """
         if self._variables_evaluated:
             return  # Already evaluated, skip (idempotent)
@@ -319,7 +406,9 @@ class Recipe:
             # (CLI will provide its own "Task not found" error)
             try:
                 reachable_tasks = collect_reachable_tasks(self.tasks, root_task)
-                variables_to_eval = collect_reachable_variables(self.tasks, self.environments, reachable_tasks)
+                variables_to_eval = collect_reachable_variables(
+                    self.tasks, self.environments, reachable_tasks
+                )
             except ValueError:
                 # Root task not found - fall back to eager evaluation
                 # This allows the recipe to be parsed even with invalid task names
@@ -336,7 +425,7 @@ class Recipe:
             self.raw_variables,
             variables_to_eval,
             self.recipe_path,
-            self._original_yaml_data
+            self._original_yaml_data,
         )
 
         # Also update the deprecated 'variables' field for backward compatibility
@@ -351,18 +440,24 @@ class Recipe:
 
             task.cmd = substitute_variables(task.cmd, self.evaluated_variables)
             task.desc = substitute_variables(task.desc, self.evaluated_variables)
-            task.working_dir = substitute_variables(task.working_dir, self.evaluated_variables)
+            task.working_dir = substitute_variables(
+                task.working_dir, self.evaluated_variables
+            )
 
             # Substitute variables in inputs (handle both string and dict inputs)
             resolved_inputs = []
             for inp in task.inputs:
                 if isinstance(inp, str):
-                    resolved_inputs.append(substitute_variables(inp, self.evaluated_variables))
+                    resolved_inputs.append(
+                        substitute_variables(inp, self.evaluated_variables)
+                    )
                 elif isinstance(inp, dict):
                     # Named input: substitute the path value
                     resolved_dict = {}
                     for name, path in inp.items():
-                        resolved_dict[name] = substitute_variables(path, self.evaluated_variables)
+                        resolved_dict[name] = substitute_variables(
+                            path, self.evaluated_variables
+                        )
                     resolved_inputs.append(resolved_dict)
                 else:
                     resolved_inputs.append(inp)
@@ -372,12 +467,16 @@ class Recipe:
             resolved_outputs = []
             for out in task.outputs:
                 if isinstance(out, str):
-                    resolved_outputs.append(substitute_variables(out, self.evaluated_variables))
+                    resolved_outputs.append(
+                        substitute_variables(out, self.evaluated_variables)
+                    )
                 elif isinstance(out, dict):
                     # Named output: substitute the path value
                     resolved_dict = {}
                     for name, path in out.items():
-                        resolved_dict[name] = substitute_variables(path, self.evaluated_variables)
+                        resolved_dict[name] = substitute_variables(
+                            path, self.evaluated_variables
+                        )
                     resolved_outputs.append(resolved_dict)
                 else:
                     resolved_outputs.append(out)
@@ -390,7 +489,9 @@ class Recipe:
             resolved_args = []
             for arg in task.args:
                 if isinstance(arg, str):
-                    resolved_args.append(substitute_variables(arg, self.evaluated_variables))
+                    resolved_args.append(
+                        substitute_variables(arg, self.evaluated_variables)
+                    )
                 elif isinstance(arg, dict):
                     # Dict arg: substitute in nested values (like default values)
                     resolved_dict = {}
@@ -400,11 +501,19 @@ class Recipe:
                             resolved_spec = {}
                             for key, value in arg_spec.items():
                                 if isinstance(value, str):
-                                    resolved_spec[key] = substitute_variables(value, self.evaluated_variables)
+                                    resolved_spec[key] = substitute_variables(
+                                        value, self.evaluated_variables
+                                    )
                                 elif isinstance(value, list):
                                     # Handle lists like 'choices'
                                     resolved_spec[key] = [
-                                        substitute_variables(v, self.evaluated_variables) if isinstance(v, str) else v
+                                        (
+                                            substitute_variables(
+                                                v, self.evaluated_variables
+                                            )
+                                            if isinstance(v, str)
+                                            else v
+                                        )
                                         for v in value
                                     ]
                                 else:
@@ -412,7 +521,11 @@ class Recipe:
                             resolved_dict[arg_name] = resolved_spec
                         else:
                             # Simple value
-                            resolved_dict[arg_name] = substitute_variables(arg_spec, self.evaluated_variables) if isinstance(arg_spec, str) else arg_spec
+                            resolved_dict[arg_name] = (
+                                substitute_variables(arg_spec, self.evaluated_variables)
+                                if isinstance(arg_spec, str)
+                                else arg_spec
+                            )
                     resolved_args.append(resolved_dict)
                 else:
                     resolved_args.append(arg)
@@ -421,15 +534,23 @@ class Recipe:
         # Substitute evaluated variables into all environments
         for env in self.environments.values():
             if env.preamble:
-                env.preamble = substitute_variables(env.preamble, self.evaluated_variables)
+                env.preamble = substitute_variables(
+                    env.preamble, self.evaluated_variables
+                )
 
             # Substitute in volumes
             if env.volumes:
-                env.volumes = [substitute_variables(vol, self.evaluated_variables) for vol in env.volumes]
+                env.volumes = [
+                    substitute_variables(vol, self.evaluated_variables)
+                    for vol in env.volumes
+                ]
 
             # Substitute in ports
             if env.ports:
-                env.ports = [substitute_variables(port, self.evaluated_variables) for port in env.ports]
+                env.ports = [
+                    substitute_variables(port, self.evaluated_variables)
+                    for port in env.ports
+                ]
 
             # Substitute in env_vars values
             if env.env_vars:
@@ -440,7 +561,9 @@ class Recipe:
 
             # Substitute in working_dir
             if env.working_dir:
-                env.working_dir = substitute_variables(env.working_dir, self.evaluated_variables)
+                env.working_dir = substitute_variables(
+                    env.working_dir, self.evaluated_variables
+                )
 
             # Substitute in build args (dict for Docker environments)
             if env.args and isinstance(env.args, dict):
@@ -454,7 +577,8 @@ class Recipe:
 
 
 def find_recipe_file(start_dir: Path | None = None) -> Path | None:
-    """Find recipe file in current or parent directories.
+    """
+    Find recipe file in current or parent directories.
 
     Looks for recipe files matching these patterns (in order of preference):
     - tasktree.yaml
@@ -466,13 +590,14 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
     with instructions to use --tasks option.
 
     Args:
-        start_dir: Directory to start searching from (defaults to cwd)
+    start_dir: Directory to start searching from (defaults to cwd)
 
     Returns:
-        Path to recipe file if found, None otherwise
+    Path to recipe file if found, None otherwise
 
     Raises:
-        ValueError: If multiple recipe files found in the same directory
+    ValueError: If multiple recipe files found in the same directory
+    @athena: 38ccb0c1bb86
     """
     if start_dir is None:
         start_dir = Path.cwd()
@@ -532,15 +657,17 @@ def find_recipe_file(start_dir: Path | None = None) -> Path | None:
 
 
 def _validate_variable_name(name: str) -> None:
-    """Validate that a variable name is a valid identifier.
+    """
+    Validate that a variable name is a valid identifier.
 
     Args:
-        name: Variable name to validate
+    name: Variable name to validate
 
     Raises:
-        ValueError: If name is not a valid identifier
+    ValueError: If name is not a valid identifier
+    @athena: 61f92f7ad278
     """
-    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', name):
+    if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", name):
         raise ValueError(
             f"Variable name '{name}' is invalid. Names must start with "
             f"letter/underscore and contain only alphanumerics and underscores."
@@ -548,23 +675,20 @@ def _validate_variable_name(name: str) -> None:
 
 
 def _infer_variable_type(value: Any) -> str:
-    """Infer type name from Python value.
+    """
+    Infer type name from Python value.
 
     Args:
-        value: Python value from YAML
+    value: Python value from YAML
 
     Returns:
-        Type name string (str, int, float, bool)
+    Type name string (str, int, float, bool)
 
     Raises:
-        ValueError: If value type is not supported
-    """
-    type_map = {
-        str: "str",
-        int: "int",
-        float: "float",
-        bool: "bool"
-    }
+    ValueError: If value type is not supported
+    @athena: 335ae24e1504
+    """
+    type_map = {str: "str", int: "int", float: "float", bool: "bool"}
     python_type = type(value)
     if python_type not in type_map:
         raise ValueError(
@@ -575,29 +699,35 @@ def _infer_variable_type(value: Any) -> str:
 
 
 def _is_env_variable_reference(value: Any) -> bool:
-    """Check if value is an environment variable reference.
+    """
+    Check if value is an environment variable reference.
 
     Args:
-        value: Raw value from YAML
+    value: Raw value from YAML
 
     Returns:
-        True if value is { env: VAR_NAME } dict
+    True if value is { env: VAR_NAME } dict
+    @athena: c01927ec19ef
     """
     return isinstance(value, dict) and "env" in value
 
 
-def _validate_env_variable_reference(var_name: str, value: dict) -> tuple[str, str | None]:
-    """Validate and extract environment variable name and optional default from reference.
+def _validate_env_variable_reference(
+    var_name: str, value: dict
+) -> tuple[str, str | None]:
+    """
+    Validate and extract environment variable name and optional default from reference.
 
     Args:
-        var_name: Name of the variable being defined
-        value: Dict that should be { env: ENV_VAR_NAME } or { env: ENV_VAR_NAME, default: "value" }
+    var_name: Name of the variable being defined
+    value: Dict that should be { env: ENV_VAR_NAME } or { env: ENV_VAR_NAME, default: "value" }
 
     Returns:
-        Tuple of (environment variable name, default value or None)
+    Tuple of (environment variable name, default value or None)
 
     Raises:
-        ValueError: If reference is invalid
+    ValueError: If reference is invalid
+    @athena: 9fc8b2333b54
     """
     # Validate dict structure - allow 'env' and optionally 'default'
     valid_keys = {"env", "default"}
@@ -605,7 +735,7 @@ def _validate_env_variable_reference(var_name: str, value: dict) -> tuple[str, s
     if invalid_keys:
         raise ValueError(
             f"Invalid environment variable reference in variable '{var_name}'.\n"
-            f"Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: \"value\" }}\n"
+            f'Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: "value" }}\n'
             f"Found invalid keys: {', '.join(invalid_keys)}"
         )
 
@@ -614,7 +744,7 @@ def _validate_env_variable_reference(var_name: str, value: dict) -> tuple[str, s
         raise ValueError(
             f"Invalid environment variable reference in variable '{var_name}'.\n"
             f"Missing required 'env' key.\n"
-            f"Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: \"value\" }}"
+            f'Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: "value" }}'
         )
 
     env_var_name = value["env"]
@@ -623,12 +753,12 @@ def _validate_env_variable_reference(var_name: str, value: dict) -> tuple[str, s
     if not env_var_name or not isinstance(env_var_name, str):
         raise ValueError(
             f"Invalid environment variable reference in variable '{var_name}'.\n"
-            f"Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: \"value\" }}"
+            f'Expected: {{ env: VARIABLE_NAME }} or {{ env: VARIABLE_NAME, default: "value" }}'
             f"Found: {{ env: {env_var_name!r} }}"
         )
 
     # Validate env var name format (allow both uppercase and mixed case for flexibility)
-    if not re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', env_var_name):
+    if not re.match(r"^[a-zA-Z_][a-zA-Z0-9_]*$", env_var_name):
         raise ValueError(
             f"Invalid environment variable name '{env_var_name}' in variable '{var_name}'.\n"
             f"Environment variable names must start with a letter or underscore,\n"
@@ -644,25 +774,29 @@ def _validate_env_variable_reference(var_name: str, value: dict) -> tuple[str, s
                 f"Invalid default value in variable '{var_name}'.\n"
                 f"Environment variable defaults must be strings.\n"
                 f"Got: {default!r} (type: {type(default).__name__})\n"
-                f"Use a quoted string: {{ env: {env_var_name}, default: \"{default}\" }}"
+                f'Use a quoted string: {{ env: {env_var_name}, default: "{default}" }}'
             )
 
     return env_var_name, default
 
 
-def _resolve_env_variable(var_name: str, env_var_name: str, default: str | None = None) -> str:
-    """Resolve environment variable value.
+def _resolve_env_variable(
+    var_name: str, env_var_name: str, default: str | None = None
+) -> str:
+    """
+    Resolve environment variable value.
 
     Args:
-        var_name: Name of the variable being defined
-        env_var_name: Name of environment variable to read
-        default: Optional default value to use if environment variable is not set
+    var_name: Name of the variable being defined
+    env_var_name: Name of environment variable to read
+    default: Optional default value to use if environment variable is not set
 
     Returns:
-        Environment variable value as string, or default if not set and default provided
+    Environment variable value as string, or default if not set and default provided
 
     Raises:
-        ValueError: If environment variable is not set and no default provided
+    ValueError: If environment variable is not set and no default provided
+    @athena: c00d3a241a99
     """
     value = os.environ.get(env_var_name, default)
 
@@ -680,29 +814,33 @@ def _resolve_env_variable(var_name: str, env_var_name: str, default: str | None
 
 
 def _is_file_read_reference(value: Any) -> bool:
-    """Check if value is a file read reference.
+    """
+    Check if value is a file read reference.
 
     Args:
-        value: Raw value from YAML
+    value: Raw value from YAML
 
     Returns:
-        True if value is { read: filepath } dict
+    True if value is { read: filepath } dict
+    @athena: da129db1b17b
     """
     return isinstance(value, dict) and "read" in value
 
 
 def _validate_file_read_reference(var_name: str, value: dict) -> str:
-    """Validate and extract filepath from file read reference.
+    """
+    Validate and extract filepath from file read reference.
 
     Args:
-        var_name: Name of the variable being defined
-        value: Dict that should be { read: filepath }
+    var_name: Name of the variable being defined
+    value: Dict that should be { read: filepath }
 
     Returns:
-        Filepath string
+    Filepath string
 
     Raises:
-        ValueError: If reference is invalid
+    ValueError: If reference is invalid
+    @athena: 2615951372fc
     """
     # Validate dict structure (only "read" key allowed)
     if len(value) != 1:
@@ -728,7 +866,8 @@ def _validate_file_read_reference(var_name: str, value: dict) -> str:
 
 
 def _resolve_file_path(filepath: str, recipe_file_path: Path) -> Path:
-    """Resolve file path relative to recipe file location.
+    """
+    Resolve file path relative to recipe file location.
 
     Handles three path types:
     1. Tilde paths (~): Expand to user home directory
@@ -736,11 +875,12 @@ def _resolve_file_path(filepath: str, recipe_file_path: Path) -> Path:
     3. Relative paths: Resolve relative to recipe file's directory
 
     Args:
-        filepath: Path string from YAML (may be relative, absolute, or tilde)
-        recipe_file_path: Path to the recipe file containing the variable
+    filepath: Path string from YAML (may be relative, absolute, or tilde)
+    recipe_file_path: Path to the recipe file containing the variable
 
     Returns:
-        Resolved absolute Path object
+    Resolved absolute Path object
+    @athena: e80470e9c7d6
     """
     # Expand tilde to home directory
     if filepath.startswith("~"):
@@ -758,18 +898,20 @@ def _resolve_file_path(filepath: str, recipe_file_path: Path) -> Path:
 
 
 def _resolve_file_variable(var_name: str, filepath: str, resolved_path: Path) -> str:
-    """Read file contents for variable value.
+    """
+    Read file contents for variable value.
 
     Args:
-        var_name: Name of the variable being defined
-        filepath: Original filepath string (for error messages)
-        resolved_path: Resolved absolute path to the file
+    var_name: Name of the variable being defined
+    filepath: Original filepath string (for error messages)
+    resolved_path: Resolved absolute path to the file
 
     Returns:
-        File contents as string (with trailing newline stripped)
+    File contents as string (with trailing newline stripped)
 
     Raises:
-        ValueError: If file doesn't exist, can't be read, or contains invalid UTF-8
+    ValueError: If file doesn't exist, can't be read, or contains invalid UTF-8
+    @athena: cab84337f145
     """
     # Check file exists
     if not resolved_path.exists():
@@ -788,7 +930,7 @@ def _resolve_file_variable(var_name: str, filepath: str, resolved_path: Path) ->
 
     # Read file with UTF-8 error handling
     try:
-        content = resolved_path.read_text(encoding='utf-8')
+        content = resolved_path.read_text(encoding="utf-8")
     except PermissionError:
         raise ValueError(
             f"Failed to read file for variable '{var_name}': {filepath}\n"
@@ -804,36 +946,40 @@ def _resolve_file_variable(var_name: str, filepath: str, resolved_path: Path) ->
         )
 
     # Strip single trailing newline if present
-    if content.endswith('\n'):
+    if content.endswith("\n"):
         content = content[:-1]
 
     return content
 
 
 def _is_eval_reference(value: Any) -> bool:
-    """Check if value is an eval command reference.
+    """
+    Check if value is an eval command reference.
 
     Args:
-        value: Raw value from YAML
+    value: Raw value from YAML
 
     Returns:
-        True if value is { eval: command } dict
+    True if value is { eval: command } dict
+    @athena: 121784f6d4ab
     """
     return isinstance(value, dict) and "eval" in value
 
 
 def _validate_eval_reference(var_name: str, value: dict) -> str:
-    """Validate and extract command from eval reference.
+    """
+    Validate and extract command from eval reference.
 
     Args:
-        var_name: Name of the variable being defined
-        value: Dict that should be { eval: command }
+    var_name: Name of the variable being defined
+    value: Dict that should be { eval: command }
 
     Returns:
-        Command string
+    Command string
 
     Raises:
-        ValueError: If reference is invalid
+    ValueError: If reference is invalid
+    @athena: f3cde1011d2d
     """
     # Validate dict structure (only "eval" key allowed)
     if len(value) != 1:
@@ -859,37 +1005,38 @@ def _validate_eval_reference(var_name: str, value: dict) -> str:
 
 
 def _get_default_shell_and_args() -> tuple[str, list[str]]:
-    """Get default shell and args for current platform.
+    """
+    Get default shell and args for current platform.
 
     Returns:
-        Tuple of (shell, args) for platform default
+    Tuple of (shell, args) for platform default
+    @athena: 475863b02b48
     """
     is_windows = platform.system() == "Windows"
     if is_windows:
-        return ("cmd", ["/c"])
+        return "cmd", ["/c"]
     else:
-        return ("bash", ["-c"])
+        return "bash", ["-c"]
 
 
 def _resolve_eval_variable(
-    var_name: str,
-    command: str,
-    recipe_file_path: Path,
-    recipe_data: dict
+    var_name: str, command: str, recipe_file_path: Path, recipe_data: dict
 ) -> str:
-    """Execute command and capture output for variable value.
+    """
+    Execute command and capture output for variable value.
 
     Args:
-        var_name: Name of the variable being defined
-        command: Command to execute
-        recipe_file_path: Path to recipe file (for working directory)
-        recipe_data: Parsed YAML data (for accessing default_env)
+    var_name: Name of the variable being defined
+    command: Command to execute
+    recipe_file_path: Path to recipe file (for working directory)
+    recipe_data: Parsed YAML data (for accessing default_env)
 
     Returns:
-        Command stdout as string (with trailing newline stripped)
+    Command stdout as string (with trailing newline stripped)
 
     Raises:
-        ValueError: If command fails or cannot be executed
+    ValueError: If command fails or cannot be executed
+    @athena: 647d3a310c77
     """
     # Determine shell to use
     shell = None
@@ -954,7 +1101,7 @@ def _resolve_eval_variable(
     output = result.stdout
 
     # Strip single trailing newline if present
-    if output.endswith('\n'):
+    if output.endswith("\n"):
         output = output[:-1]
 
     return output
@@ -966,23 +1113,25 @@ def _resolve_variable_value(
     resolved: dict[str, str],
     resolution_stack: list[str],
     file_path: Path,
-    recipe_data: dict | None = None
+    recipe_data: dict | None = None,
 ) -> str:
-    """Resolve a single variable value with circular reference detection.
+    """
+    Resolve a single variable value with circular reference detection.
 
     Args:
-        name: Variable name being resolved
-        raw_value: Raw value from YAML (int, str, bool, float, dict with env/read/eval)
-        resolved: Dictionary of already-resolved variables
-        resolution_stack: Stack of variables currently being resolved (for circular detection)
-        file_path: Path to recipe file (for resolving relative file paths in { read: ... })
-        recipe_data: Parsed YAML data (for accessing default_env in { eval: ... })
+    name: Variable name being resolved
+    raw_value: Raw value from YAML (int, str, bool, float, dict with env/read/eval)
+    resolved: Dictionary of already-resolved variables
+    resolution_stack: Stack of variables currently being resolved (for circular detection)
+    file_path: Path to recipe file (for resolving relative file paths in { read: ... })
+    recipe_data: Parsed YAML data (for accessing default_env in { eval: ... })
 
     Returns:
-        Resolved string value
+    Resolved string value
 
     Raises:
-        ValueError: If circular reference detected or validation fails
+    ValueError: If circular reference detected or validation fails
+    @athena: da94de106756
     """
     # Check for circular reference
     if name in resolution_stack:
@@ -1002,6 +1151,7 @@ def _resolve_variable_value(
 
             # Still perform variable-in-variable substitution
             from tasktree.substitution import substitute_variables
+
             try:
                 resolved_value = substitute_variables(string_value, resolved)
             except ValueError as e:
@@ -1013,7 +1163,9 @@ def _resolve_variable_value(
                         undefined_var = match.group(1)
                         if undefined_var in resolution_stack:
                             cycle = " -> ".join(resolution_stack + [undefined_var])
-                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                            raise ValueError(
+                                f"Circular reference detected in variables: {cycle}"
+                            )
                 # Re-raise the original error if not circular
                 raise
 
@@ -1032,6 +1184,7 @@ def _resolve_variable_value(
 
             # Still perform variable-in-variable substitution
             from tasktree.substitution import substitute_variables
+
             try:
                 resolved_value = substitute_variables(string_value, resolved)
             except ValueError as e:
@@ -1043,7 +1196,9 @@ def _resolve_variable_value(
                         undefined_var = match.group(1)
                         if undefined_var in resolution_stack:
                             cycle = " -> ".join(resolution_stack + [undefined_var])
-                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                            raise ValueError(
+                                f"Circular reference detected in variables: {cycle}"
+                            )
                 # Re-raise the original error if not circular
                 raise
 
@@ -1059,6 +1214,7 @@ def _resolve_variable_value(
 
             # Still perform variable-in-variable substitution
             from tasktree.substitution import substitute_variables
+
             try:
                 resolved_value = substitute_variables(string_value, resolved)
             except ValueError as e:
@@ -1070,7 +1226,9 @@ def _resolve_variable_value(
                         undefined_var = match.group(1)
                         if undefined_var in resolution_stack:
                             cycle = " -> ".join(resolution_stack + [undefined_var])
-                            raise ValueError(f"Circular reference detected in variables: {cycle}")
+                            raise ValueError(
+                                f"Circular reference detected in variables: {cycle}"
+                            )
                 # Re-raise the original error if not circular
                 raise
 
@@ -1079,6 +1237,7 @@ def _resolve_variable_value(
         # Validate and infer type
         type_name = _infer_variable_type(raw_value)
         from tasktree.types import get_click_type
+
         validator = get_click_type(type_name)
 
         # Validate and stringify the value
@@ -1092,6 +1251,7 @@ def _resolve_variable_value(
 
         # Substitute any {{ var.name }} references in the string value
         from tasktree.substitution import substitute_variables
+
         try:
             resolved_value = substitute_variables(string_value_str, resolved)
         except ValueError as e:
@@ -1104,7 +1264,9 @@ def _resolve_variable_value(
                     undefined_var = match.group(1)
                     if undefined_var in resolution_stack:
                         cycle = " -> ".join(resolution_stack + [undefined_var])
-                        raise ValueError(f"Circular reference detected in variables: {cycle}")
+                        raise ValueError(
+                            f"Circular reference detected in variables: {cycle}"
+                        )
             # Re-raise the original error if not circular
             raise
 
@@ -1114,20 +1276,22 @@ def _resolve_variable_value(
 
 
 def _parse_variables_section(data: dict, file_path: Path) -> dict[str, str]:
-    """Parse and resolve the variables section from YAML data.
+    """
+    Parse and resolve the variables section from YAML data.
 
     Variables are resolved in order, allowing variables to reference
     previously-defined variables using {{ var.name }} syntax.
 
     Args:
-        data: Parsed YAML data (root level)
-        file_path: Path to the recipe file (for resolving relative file paths)
+    data: Parsed YAML data (root level)
+    file_path: Path to the recipe file (for resolving relative file paths)
 
     Returns:
-        Dictionary mapping variable names to resolved string values
+    Dictionary mapping variable names to resolved string values
 
     Raises:
-        ValueError: For validation errors, undefined refs, or circular refs
+    ValueError: For validation errors, undefined refs, or circular refs
+    @athena: aa45e860a958
     """
     if "variables" not in data:
         return {}
@@ -1149,33 +1313,34 @@ def _parse_variables_section(data: dict, file_path: Path) -> dict[str, str]:
 
 
 def _expand_variable_dependencies(
-    variable_names: set[str],
-    raw_variables: dict[str, Any]
+    variable_names: set[str], raw_variables: dict[str, Any]
 ) -> set[str]:
-    """Expand variable set to include all transitively referenced variables.
+    """
+    Expand variable set to include all transitively referenced variables.
 
     If variable A references variable B, and B references C, then requesting A
     should also evaluate B and C.
 
     Args:
-        variable_names: Initial set of variable names
-        raw_variables: Raw variable definitions from YAML
+    variable_names: Initial set of variable names
+    raw_variables: Raw variable definitions from YAML
 
     Returns:
-        Expanded set including all transitively referenced variables
+    Expanded set including all transitively referenced variables
 
     Example:
-        >>> raw_vars = {
-        ...     "a": "{{ var.b }}",
-        ...     "b": "{{ var.c }}",
-        ...     "c": "value"
-        ... }
-        >>> _expand_variable_dependencies({"a"}, raw_vars)
-        {"a", "b", "c"}
+    >>> raw_vars = {
+    ...     "a": "{{ var.b }}",
+    ...     "b": "{{ var.c }}",
+    ...     "c": "value"
+    ... }
+    >>> _expand_variable_dependencies({"a"}, raw_vars)
+    {"a", "b", "c"}
+    @athena: 98e583b402aa
     """
     expanded = set(variable_names)
     to_process = list(variable_names)
-    pattern = re.compile(r'\{\{\s*var\.(\w+)\s*\}\}')
+    pattern = re.compile(r"\{\{\s*var\.(\w+)\s*}}")
 
     while to_process:
         var_name = to_process.pop(0)
@@ -1194,8 +1359,8 @@ def _expand_variable_dependencies(
                     expanded.add(referenced_var)
                     to_process.append(referenced_var)
         # Handle { read: filepath } variables - check file contents for variable references
-        elif isinstance(raw_value, dict) and 'read' in raw_value:
-            filepath = raw_value['read']
+        elif isinstance(raw_value, dict) and "read" in raw_value:
+            filepath = raw_value["read"]
             # For dependency expansion, we speculatively read files to find variable references
             # This is acceptable because file reads are relatively cheap compared to eval commands
             try:
@@ -1203,6 +1368,7 @@ def _expand_variable_dependencies(
                 # Skip if filepath is None or empty (validation error will be caught during evaluation)
                 if filepath and isinstance(filepath, str):
                     from pathlib import Path
+
                     if Path(filepath).exists():
                         file_content = Path(filepath).read_text()
                         # Extract variable references from file content
@@ -1216,8 +1382,12 @@ def _expand_variable_dependencies(
                 # The error will be caught during actual evaluation
                 pass
         # Handle { env: VAR, default: ... } variables - check default value for variable references
-        elif isinstance(raw_value, dict) and 'env' in raw_value and 'default' in raw_value:
-            default_value = raw_value['default']
+        elif (
+            isinstance(raw_value, dict)
+            and "env" in raw_value
+            and "default" in raw_value
+        ):
+            default_value = raw_value["default"]
             # Check if default value contains variable references
             if isinstance(default_value, str):
                 for match in pattern.finditer(default_value):
@@ -1230,12 +1400,10 @@ def _expand_variable_dependencies(
 
 
 def _evaluate_variable_subset(
-    raw_variables: dict[str, Any],
-    variable_names: set[str],
-    file_path: Path,
-    data: dict
+    raw_variables: dict[str, Any], variable_names: set[str], file_path: Path, data: dict
 ) -> dict[str, str]:
-    """Evaluate only specified variables from raw specs (for lazy evaluation).
+    """
+    Evaluate only specified variables from raw specs (for lazy evaluation).
 
     This function is similar to _parse_variables_section but only evaluates
     a subset of variables. This enables lazy evaluation where only reachable
@@ -1245,21 +1413,22 @@ def _evaluate_variable_subset(
     variable B, both will be evaluated even if only A was explicitly requested.
 
     Args:
-        raw_variables: Raw variable definitions from YAML (not yet evaluated)
-        variable_names: Set of variable names to evaluate
-        file_path: Recipe file path (for relative file resolution)
-        data: Full YAML data (for context in _resolve_variable_value)
+    raw_variables: Raw variable definitions from YAML (not yet evaluated)
+    variable_names: Set of variable names to evaluate
+    file_path: Recipe file path (for relative file resolution)
+    data: Full YAML data (for context in _resolve_variable_value)
 
     Returns:
-        Dictionary of evaluated variable values (for specified variables and their dependencies)
+    Dictionary of evaluated variable values (for specified variables and their dependencies)
 
     Raises:
-        ValueError: For validation errors, undefined refs, or circular refs
+    ValueError: For validation errors, undefined refs, or circular refs
 
     Example:
-        >>> raw_vars = {"a": "{{ var.b }}", "b": "value", "c": "unused"}
-        >>> _evaluate_variable_subset(raw_vars, {"a"}, path, data)
-        {"a": "value", "b": "value"}  # "a" and its dependency "b", but not "c"
+    >>> raw_vars = {"a": "{{ var.b }}", "b": "value", "c": "unused"}
+    >>> _evaluate_variable_subset(raw_vars, {"a"}, path, data)
+    {"a": "value", "b": "value"}  # "a" and its dependency "b", but not "c"
+    @athena: 1e9d491d7404
     """
     if not isinstance(raw_variables, dict):
         raise ValueError("'variables' must be a dictionary")
@@ -1286,18 +1455,22 @@ def _parse_file_with_env(
     namespace: str | None,
     project_root: Path,
     import_stack: list[Path] | None = None,
-) -> tuple[dict[str, Task], dict[str, Environment], str, dict[str, Any], dict[str, Any]]:
-    """Parse file and extract tasks, environments, and variables.
+) -> tuple[
+    dict[str, Task], dict[str, Environment], str, dict[str, Any], dict[str, Any]
+]:
+    """
+    Parse file and extract tasks, environments, and variables.
 
     Args:
-        file_path: Path to YAML file
-        namespace: Optional namespace prefix for tasks
-        project_root: Root directory of the project
-        import_stack: Stack of files being imported (for circular detection)
+    file_path: Path to YAML file
+    namespace: Optional namespace prefix for tasks
+    project_root: Root directory of the project
+    import_stack: Stack of files being imported (for circular detection)
 
     Returns:
-        Tuple of (tasks, environments, default_env_name, raw_variables, yaml_data)
-        Note: Variables are NOT evaluated here - they're stored as raw specs for lazy evaluation
+    Tuple of (tasks, environments, default_env_name, raw_variables, YAML_data)
+    Note: Variables are NOT evaluated here - they're stored as raw specs for lazy evaluation
+    @athena: b2dced506787
     """
     # Parse tasks normally
     tasks = _parse_file(file_path, namespace, project_root, import_stack)
@@ -1413,32 +1586,34 @@ def _parse_file_with_env(
                         env_vars=env_vars,
                         working_dir=working_dir,
                         extra_args=extra_args,
-                        run_as_root=run_as_root
+                        run_as_root=run_as_root,
                     )
 
     return tasks, environments, default_env, raw_variables, yaml_data
 
 
 def collect_reachable_tasks(tasks: dict[str, Task], root_task: str) -> set[str]:
-    """Collect all tasks reachable from the root task via dependencies.
+    """
+    Collect all tasks reachable from the root task via dependencies.
 
     Uses BFS to traverse the dependency graph and collect all task names
     that could potentially be executed when running the root task.
 
     Args:
-        tasks: Dictionary mapping task names to Task objects
-        root_task: Name of the root task to start traversal from
+    tasks: Dictionary mapping task names to Task objects
+    root_task: Name of the root task to start traversal from
 
     Returns:
-        Set of task names reachable from root_task (includes root_task itself)
+    Set of task names reachable from root_task (includes root_task itself)
 
     Raises:
-        ValueError: If root_task doesn't exist
+    ValueError: If root_task doesn't exist
 
     Example:
-        >>> tasks = {"a": Task("a", deps=["b"]), "b": Task("b", deps=[]), "c": Task("c", deps=[])}
-        >>> collect_reachable_tasks(tasks, "a")
-        {"a", "b"}
+    >>> tasks = {"a": Task("a", deps=["b"]), "b": Task("b", deps=[]), "c": Task("c", deps=[])}
+    >>> collect_reachable_tasks(tasks, "a")
+    {"a", "b"}
+    @athena: fe29d8558be3
     """
     if root_task not in tasks:
         raise ValueError(f"Root task '{root_task}' not found in recipe")
@@ -1480,30 +1655,32 @@ def collect_reachable_tasks(tasks: dict[str, Task], root_task: str) -> set[str]:
 def collect_reachable_variables(
     tasks: dict[str, Task],
     environments: dict[str, Environment],
-    reachable_task_names: set[str]
+    reachable_task_names: set[str],
 ) -> set[str]:
-    """Extract variable names used by reachable tasks.
+    """
+    Extract variable names used by reachable tasks.
 
     Searches for {{ var.* }} placeholders in task and environment definitions to determine
     which variables are actually needed for execution.
 
     Args:
-        tasks: Dictionary mapping task names to Task objects
-        environments: Dictionary mapping environment names to Environment objects
-        reachable_task_names: Set of task names that will be executed
+    tasks: Dictionary mapping task names to Task objects
+    environments: Dictionary mapping environment names to Environment objects
+    reachable_task_names: Set of task names that will be executed
 
     Returns:
-        Set of variable names referenced by reachable tasks
+    Set of variable names referenced by reachable tasks
 
     Example:
-        >>> task = Task("build", cmd="echo {{ var.version }}")
-        >>> collect_reachable_variables({"build": task}, {"build"})
-        {"version"}
+    >>> task = Task("build", cmd="echo {{ var.version }}")
+    >>> collect_reachable_variables({"build": task}, {"build"})
+    {"version"}
+    @athena: e22e54537f8d
     """
     import re
 
     # Pattern to match {{ var.name }}
-    var_pattern = re.compile(r'\{\{\s*var\s*\.\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}')
+    var_pattern = re.compile(r"\{\{\s*var\s*\.\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*}}")
 
     variables = set()
 
@@ -1622,32 +1799,32 @@ def collect_reachable_variables(
 
 
 def parse_recipe(
-    recipe_path: Path,
-    project_root: Path | None = None,
-    root_task: str | None = None
+    recipe_path: Path, project_root: Path | None = None, root_task: str | None = None
 ) -> Recipe:
-    """Parse a recipe file and handle imports recursively.
+    """
+    Parse a recipe file and handle imports recursively.
 
     This function now implements lazy variable evaluation: if root_task is provided,
     only variables reachable from that task will be evaluated. This provides significant
     performance and security benefits for recipes with many variables.
 
     Args:
-        recipe_path: Path to the main recipe file
-        project_root: Optional project root directory. If not provided, uses recipe file's parent directory.
-                     When using --tasks option, this should be the current working directory.
-        root_task: Optional root task for lazy variable evaluation. If provided, only variables
-                  used by tasks reachable from root_task will be evaluated (optimization).
-                  If None, all variables will be evaluated (for --list command compatibility).
+    recipe_path: Path to the main recipe file
+    project_root: Optional project root directory. If not provided, uses recipe file's parent directory.
+    When using --tasks option, this should be the current working directory.
+    root_task: Optional root task for lazy variable evaluation. If provided, only variables
+    used by tasks reachable from root_task will be evaluated (optimization).
+    If None, all variables will be evaluated (for --list command compatibility).
 
     Returns:
-        Recipe object with all tasks (including recursively imported tasks) and evaluated variables
+    Recipe object with all tasks (including recursively imported tasks) and evaluated variables
 
     Raises:
-        FileNotFoundError: If recipe file doesn't exist
-        CircularImportError: If circular imports are detected
-        yaml.YAMLError: If YAML is invalid
-        ValueError: If recipe structure is invalid
+    FileNotFoundError: If recipe file doesn't exist
+    CircularImportError: If circular imports are detected
+    yaml.YAMLError: If YAML is invalid
+    ValueError: If recipe structure is invalid
+    @athena: 27326e37d5f3
     """
     if not recipe_path.exists():
         raise FileNotFoundError(f"Recipe file not found: {recipe_path}")
@@ -1673,7 +1850,7 @@ def parse_recipe(
         raw_variables=raw_variables,
         evaluated_variables={},  # Empty initially
         _variables_evaluated=False,
-        _original_yaml_data=yaml_data
+        _original_yaml_data=yaml_data,
     )
 
     # Trigger lazy variable evaluation
@@ -1690,21 +1867,23 @@ def _parse_file(
     project_root: Path,
     import_stack: list[Path] | None = None,
 ) -> dict[str, Task]:
-    """Parse a single YAML file and return tasks, recursively processing imports.
+    """
+    Parse a single YAML file and return tasks, recursively processing imports.
 
     Args:
-        file_path: Path to YAML file
-        namespace: Optional namespace prefix for tasks
-        project_root: Root directory of the project
-        import_stack: Stack of files being imported (for circular detection)
+    file_path: Path to YAML file
+    namespace: Optional namespace prefix for tasks
+    project_root: Root directory of the project
+    import_stack: Stack of files being imported (for circular detection)
 
     Returns:
-        Dictionary of task name to Task objects
+    Dictionary of task name to Task objects
 
     Raises:
-        CircularImportError: If a circular import is detected
-        FileNotFoundError: If an imported file doesn't exist
-        ValueError: If task structure is invalid
+    CircularImportError: If a circular import is detected
+    FileNotFoundError: If an imported file doesn't exist
+    ValueError: If task structure is invalid
+    @athena: 8a903d791c2f
     """
     # Initialize import stack if not provided
     if import_stack is None:
@@ -1726,7 +1905,8 @@ def _parse_file(
         data = {}
 
     tasks: dict[str, Task] = {}
-    file_dir = file_path.parent
+    # TODO: Understand why this is not used.
+    # file_dir = file_path.parent
 
     # Default working directory is the project root (where tt is invoked)
     # NOT the directory where the tasks file is located
@@ -1746,7 +1926,9 @@ def _parse_file(
             local_import_namespaces.add(child_namespace)
 
             # Build full namespace chain
-            full_namespace = f"{namespace}.{child_namespace}" if namespace else child_namespace
+            full_namespace = (
+                f"{namespace}.{child_namespace}" if namespace else child_namespace
+            )
 
             # Resolve import path relative to current file's directory
             child_path = file_path.parent / child_file
@@ -1764,15 +1946,16 @@ def _parse_file(
             tasks.update(nested_tasks)
 
     # Validate top-level keys (only imports, environments, tasks, and variables are allowed)
-    VALID_TOP_LEVEL_KEYS = {"imports", "environments", "tasks", "variables"}
+    valid_top_level_keys = {"imports", "environments", "tasks", "variables"}
 
     # Check if tasks key is missing when there appear to be task definitions at root
     # Do this BEFORE checking for unknown keys, to provide better error message
     if "tasks" not in data and data:
         # Check if there are potential task definitions at root level
         potential_tasks = [
-            k for k, v in data.items()
-            if isinstance(v, dict) and k not in VALID_TOP_LEVEL_KEYS
+            k
+            for k, v in data.items()
+            if isinstance(v, dict) and k not in valid_top_level_keys
         ]
 
         if potential_tasks:
@@ -1782,13 +1965,13 @@ def _parse_file(
                 f"Found these keys at root level: {', '.join(potential_tasks)}\n\n"
                 f"Did you mean:\n\n"
                 f"tasks:\n"
-                + '\n'.join(f"  {k}:" for k in potential_tasks) +
-                "\n    cmd: ...\n\n"
-                f"Valid top-level keys are: {', '.join(sorted(VALID_TOP_LEVEL_KEYS))}"
+                + "\n".join(f"  {k}:" for k in potential_tasks)
+                + "\n    cmd: ...\n\n"
+                f"Valid top-level keys are: {', '.join(sorted(valid_top_level_keys))}"
             )
 
     # Now check for other invalid top-level keys (non-dict values)
-    invalid_keys = set(data.keys()) - VALID_TOP_LEVEL_KEYS
+    invalid_keys = set(data.keys()) - valid_top_level_keys
     if invalid_keys:
         raise ValueError(
             f"Invalid recipe format in {file_path}\n\n"
@@ -1806,10 +1989,14 @@ def _parse_file(
 
     # Process local tasks
     for task_name, task_data in tasks_data.items():
-
         if not isinstance(task_data, dict):
             raise ValueError(f"Task '{task_name}' must be a dictionary")
 
+        if "." in task_name:
+            raise ValueError(
+                f"Task name '{task_name}' cannot contain dots (reserved for namespacing)"
+            )
+
         if "cmd" not in task_data:
             raise ValueError(f"Task '{task_name}' missing required 'cmd' field")
 
@@ -1847,19 +2034,19 @@ def _parse_file(
                 elif isinstance(dep, dict):
                     # Dict dependency with args - rewrite the task name key
                     rewritten_dep = {}
-                    for task_name, args in dep.items():
-                        if "." not in task_name:
+                    for t_name, args in dep.items():
+                        if "." not in t_name:
                             # Simple name - prefix it
-                            rewritten_dep[f"{namespace}.{task_name}"] = args
+                            rewritten_dep[f"{namespace}.{t_name}"] = args
                         else:
                             # Check if it starts with a local import namespace
-                            dep_root = task_name.split(".", 1)[0]
+                            dep_root = t_name.split(".", 1)[0]
                             if dep_root in local_import_namespaces:
                                 # Local import reference - prefix it
-                                rewritten_dep[f"{namespace}.{task_name}"] = args
+                                rewritten_dep[f"{namespace}.{t_name}"] = args
                             else:
                                 # External reference - keep as-is
-                                rewritten_dep[task_name] = args
+                                rewritten_dep[t_name] = args
                     rewritten_deps.append(rewritten_dep)
                 else:
                     # Unknown type - keep as-is
@@ -1893,15 +2080,17 @@ def _parse_file(
 
 
 def _check_case_sensitive_arg_collisions(args: list[str], task_name: str) -> None:
-    """Check for exported arguments that differ only in case.
+    """
+    Check for exported arguments that differ only in case.
 
     On Unix systems, environment variables are case-sensitive, but having
     args that differ only in case (e.g., $Server and $server) can be confusing.
     This function emits a warning if such collisions are detected.
 
     Args:
-        args: List of argument specifications
-        task_name: Name of the task (for warning message)
+    args: List of argument specifications
+    task_name: Name of the task (for warning message)
+    @athena: a3f0f3b184a8
     """
     import sys
 
@@ -1924,48 +2113,50 @@ def _check_case_sensitive_arg_collisions(args: list[str], task_name: str) -> Non
                     f"Warning: Task '{task_name}' has exported arguments that differ only in case: "
                     f"${other_name} and ${name}. "
                     f"This may be confusing on case-sensitive systems.",
-                    file=sys.stderr
+                    file=sys.stderr,
                 )
         else:
             seen_lower[lower_name] = name
 
 
 def parse_arg_spec(arg_spec: str | dict) -> ArgSpec:
-    """Parse argument specification from YAML.
+    """
+    Parse argument specification from YAML.
 
     Supports both string format and dictionary format:
 
     String format (simple names only):
-        - Simple name: "argname"
-        - Exported (becomes env var): "$argname"
+    - Simple name: "argname"
+    - Exported (becomes env var): "$argname"
 
     Dictionary format:
-        - argname: { default: "value" }
-        - argname: { type: int, default: 42 }
-        - argname: { type: int, min: 1, max: 100 }
-        - argname: { type: str, choices: ["dev", "staging", "prod"] }
-        - $argname: { default: "value" }  # Exported (type not allowed)
+    - argname: { default: "value" }
+    - argname: { type: int, default: 42 }
+    - argname: { type: int, min: 1, max: 100 }
+    - argname: { type: str, choices: ["dev", "staging", "prod"] }
+    - $argname: { default: "value" }  # Exported (type not allowed)
 
     Args:
-        arg_spec: Argument specification (string or dict with single key)
+    arg_spec: Argument specification (string or dict with single key)
 
     Returns:
-        ArgSpec object containing parsed argument information
+    ArgSpec object containing parsed argument information
 
     Examples:
-        >>> parse_arg_spec("environment")
-        ArgSpec(name='environment', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=None)
-        >>> parse_arg_spec({"key2": {"default": "foo"}})
-        ArgSpec(name='key2', arg_type='str', default='foo', is_exported=False, min_val=None, max_val=None, choices=None)
-        >>> parse_arg_spec({"key3": {"type": "int", "default": 42}})
-        ArgSpec(name='key3', arg_type='int', default='42', is_exported=False, min_val=None, max_val=None, choices=None)
-        >>> parse_arg_spec({"replicas": {"type": "int", "min": 1, "max": 100}})
-        ArgSpec(name='replicas', arg_type='int', default=None, is_exported=False, min_val=1, max_val=100, choices=None)
-        >>> parse_arg_spec({"env": {"type": "str", "choices": ["dev", "prod"]}})
-        ArgSpec(name='env', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=['dev', 'prod'])
+    >>> parse_arg_spec("environment")
+    ArgSpec(name='environment', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=None)
+    >>> parse_arg_spec({"key2": {"default": "foo"}})
+    ArgSpec(name='key2', arg_type='str', default='foo', is_exported=False, min_val=None, max_val=None, choices=None)
+    >>> parse_arg_spec({"key3": {"type": "int", "default": 42}})
+    ArgSpec(name='key3', arg_type='int', default='42', is_exported=False, min_val=None, max_val=None, choices=None)
+    >>> parse_arg_spec({"replicas": {"type": "int", "min": 1, "max": 100}})
+    ArgSpec(name='replicas', arg_type='int', default=None, is_exported=False, min_val=1, max_val=100, choices=None)
+    >>> parse_arg_spec({"env": {"type": "str", "choices": ["dev", "prod"]}})
+    ArgSpec(name='env', arg_type='str', default=None, is_exported=False, min_val=None, max_val=None, choices=['dev', 'prod'])
 
     Raises:
-        ValueError: If argument specification is invalid
+    ValueError: If argument specification is invalid
+    @athena: 2a4c7e804622
     """
     # Handle dictionary format: { argname: { type: ..., default: ... } }
     if isinstance(arg_spec, dict):
@@ -2023,23 +2214,25 @@ def parse_arg_spec(arg_spec: str | dict) -> ArgSpec:
         is_exported=is_exported,
         min_val=None,
         max_val=None,
-        choices=None
+        choices=None,
     )
 
 
 def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
-    """Parse argument specification from dictionary format.
+    """
+    Parse argument specification from dictionary format.
 
     Args:
-        arg_name: Name of the argument
-        config: Dictionary with optional keys: type, default, min, max, choices
-        is_exported: Whether argument should be exported to environment
+    arg_name: Name of the argument
+    config: Dictionary with optional keys: type, default, min, max, choices
+    is_exported: Whether argument should be exported to environment
 
     Returns:
-        ArgSpec object containing the parsed argument specification
+    ArgSpec object containing the parsed argument specification
 
     Raises:
-        ValueError: If dictionary format is invalid
+    ValueError: If dictionary format is invalid
+    @athena: 5b6b93a3612a
     """
     # Validate dictionary keys
     valid_keys = {"type", "default", "min", "max", "choices"}
@@ -2073,22 +2266,18 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
             f"Exported argument '${arg_name}' must have a string default value.\n"
             f"Got: {default!r} (type: {type(default).__name__})\n"
             f"Exported arguments become environment variables, which are always strings.\n"
-            f"Use a quoted string: ${arg_name}: {{ default: \"{default}\" }}"
+            f'Use a quoted string: ${arg_name}: {{ default: "{default}" }}'
         )
 
     # Validate choices
     if choices is not None:
         # Validate choices is a list
         if not isinstance(choices, list):
-            raise ValueError(
-                f"Argument '{arg_name}': choices must be a list"
-            )
+            raise ValueError(f"Argument '{arg_name}': choices must be a list")
 
         # Validate choices is not empty
         if len(choices) == 0:
-            raise ValueError(
-                f"Argument '{arg_name}': choices list cannot be empty"
-            )
+            raise ValueError(f"Argument '{arg_name}': choices list cannot be empty")
 
         # Check for mutual exclusivity with min/max
         if min_val is not None or max_val is not None:
@@ -2117,7 +2306,9 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
             for value_name, value_type in inferred_types[1:]:
                 if value_type != first_type:
                     # Build error message showing the conflicting types
-                    type_info = ", ".join([f"{name}={vtype}" for name, vtype in inferred_types])
+                    type_info = ", ".join(
+                        [f"{name}={vtype}" for name, vtype in inferred_types]
+                    )
                     raise ValueError(
                         f"Argument '{arg_name}': inconsistent types inferred from min, max, and default.\n"
                         f"All values must have the same type.\n"
@@ -2141,7 +2332,10 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
                 )
 
     # Validate min/max are only used with numeric types
-    if (min_val is not None or max_val is not None) and arg_type not in ("int", "float"):
+    if (min_val is not None or max_val is not None) and arg_type not in (
+        "int",
+        "float",
+    ):
         raise ValueError(
             f"Argument '{arg_name}': min/max constraints are only supported for 'int' and 'float' types, "
             f"not '{arg_type}'"
@@ -2270,12 +2464,15 @@ def _parse_arg_dict(arg_name: str, config: dict, is_exported: bool) -> ArgSpec:
         is_exported=is_exported,
         min_val=min_val,
         max_val=max_val,
-        choices=choices
+        choices=choices,
     )
 
 
-def parse_dependency_spec(dep_spec: str | dict[str, Any], recipe: Recipe) -> DependencyInvocation:
-    """Parse a dependency specification into a DependencyInvocation.
+def parse_dependency_spec(
+    dep_spec: str | dict[str, Any], recipe: Recipe
+) -> DependencyInvocation:
+    """
+    Parse a dependency specification into a DependencyInvocation.
 
     Supports three forms:
     1. Simple string: "task_name" -> DependencyInvocation(task_name, None)
@@ -2283,14 +2480,15 @@ def parse_dependency_spec(dep_spec: str | dict[str, Any], recipe: Recipe) -> Dep
     3. Named args: {"task_name": {arg1: val1}} -> DependencyInvocation(task_name, {arg1: val1})
 
     Args:
-        dep_spec: Dependency specification (string or dict)
-        recipe: Recipe containing task definitions (for arg normalization)
+    dep_spec: Dependency specification (string or dict)
+    recipe: Recipe containing task definitions (for arg normalization)
 
     Returns:
-        DependencyInvocation object with normalized args
+    DependencyInvocation object with normalized args
 
     Raises:
-        ValueError: If dependency specification is invalid
+    ValueError: If dependency specification is invalid
+    @athena: d30ff06259c2
     """
     # Simple string case
     if isinstance(dep_spec, str):
@@ -2339,17 +2537,19 @@ def parse_dependency_spec(dep_spec: str | dict[str, Any], recipe: Recipe) -> Dep
 
 
 def _get_validated_task(task_name: str, recipe: Recipe) -> Task:
-    """Get and validate that a task exists in the recipe.
+    """
+    Get and validate that a task exists in the recipe.
 
     Args:
-        task_name: Name of the task to retrieve
-        recipe: Recipe containing task definitions
+    task_name: Name of the task to retrieve
+    recipe: Recipe containing task definitions
 
     Returns:
-        The validated Task object
+    The validated Task object
 
     Raises:
-        ValueError: If task is not found
+    ValueError: If task is not found
+    @athena: 674f077e3977
     """
     task = recipe.get_task(task_name)
     if task is None:
@@ -2360,18 +2560,20 @@ def _get_validated_task(task_name: str, recipe: Recipe) -> Task:
 def _parse_positional_dependency_args(
     task_name: str, args_list: list[Any], recipe: Recipe
 ) -> DependencyInvocation:
-    """Parse positional dependency arguments.
+    """
+    Parse positional dependency arguments.
 
     Args:
-        task_name: Name of the dependency task
-        args_list: List of positional argument values
-        recipe: Recipe containing task definitions
+    task_name: Name of the dependency task
+    args_list: List of positional argument values
+    recipe: Recipe containing task definitions
 
     Returns:
-        DependencyInvocation with normalized named args
+    DependencyInvocation with normalized named args
 
     Raises:
-        ValueError: If validation fails
+    ValueError: If validation fails
+    @athena: 4d1c7957e2dd
     """
     # Get the task to validate against
     task = _get_validated_task(task_name, recipe)
@@ -2396,7 +2598,9 @@ def _parse_positional_dependency_args(
         spec = parsed_specs[i]
         if isinstance(value, str):
             # Convert string values using type validator
-            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            click_type = get_click_type(
+                spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+            )
             args_dict[spec.name] = click_type.convert(value, None, None)
         else:
             # Value is already typed (e.g., bool, int from YAML)
@@ -2407,7 +2611,9 @@ def _parse_positional_dependency_args(
         spec = parsed_specs[i]
         if spec.default is not None:
             # Defaults in task specs are always strings, convert them
-            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            click_type = get_click_type(
+                spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+            )
             args_dict[spec.name] = click_type.convert(spec.default, None, None)
         else:
             raise ValueError(
@@ -2420,18 +2626,20 @@ def _parse_positional_dependency_args(
 def _parse_named_dependency_args(
     task_name: str, args_dict: dict[str, Any], recipe: Recipe
 ) -> DependencyInvocation:
-    """Parse named dependency arguments.
+    """
+    Parse named dependency arguments.
 
     Args:
-        task_name: Name of the dependency task
-        args_dict: Dictionary of argument names to values
-        recipe: Recipe containing task definitions
+    task_name: Name of the dependency task
+    args_dict: Dictionary of argument names to values
+    recipe: Recipe containing task definitions
 
     Returns:
-        DependencyInvocation with normalized args (defaults filled)
+    DependencyInvocation with normalized args (defaults filled)
 
     Raises:
-        ValueError: If validation fails
+    ValueError: If validation fails
+    @athena: c522211de525
     """
     # Get the task to validate against
     task = _get_validated_task(task_name, recipe)
@@ -2450,9 +2658,7 @@ def _parse_named_dependency_args(
     # Validate all provided arg names exist
     for arg_name in args_dict:
         if arg_name not in spec_map:
-            raise ValueError(
-                f"Task '{task_name}' has no argument named '{arg_name}'"
-            )
+            raise ValueError(f"Task '{task_name}' has no argument named '{arg_name}'")
 
     # Build normalized args dict with defaults
     normalized_args = {}
@@ -2461,14 +2667,18 @@ def _parse_named_dependency_args(
             # Use provided value with type conversion (only convert strings)
             value = args_dict[spec.name]
             if isinstance(value, str):
-                click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+                click_type = get_click_type(
+                    spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+                )
                 normalized_args[spec.name] = click_type.convert(value, None, None)
             else:
                 # Value is already typed (e.g., bool, int from YAML)
                 normalized_args[spec.name] = value
         elif spec.default is not None:
             # Use default value (defaults are always strings in task specs)
-            click_type = get_click_type(spec.arg_type, min_val=spec.min_val, max_val=spec.max_val)
+            click_type = get_click_type(
+                spec.arg_type, min_val=spec.min_val, max_val=spec.max_val
+            )
             normalized_args[spec.name] = click_type.convert(spec.default, None, None)
         else:
             # Required arg not provided