Add CI validation for hook ordering prefixes

The ci-framework's run_hook module sorts hooks alphabetically by name
before executing them. When a pre_stage_run or post_stage_run stage has
two or more hooks, this alphabetical sorting can silently alter the
intended execution order unless each hook name carries a zero-padded
numeric prefix (e.g. "01 Install operator", "02 Create site").

Add .ci/validate-hook-ordering.py to enforce that:
- Every hook in a multi-hook stage has a numeric prefix.
- Prefixes are sequential with no gaps or duplicates.

Wire the script into the GitHub Actions workflow
(.github/workflows/automation-schema.yaml) by renaming the files_exist
job to validate_automation and adding a step to run the new validator.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: abays

.ci/validate-hook-ordering.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Validate numeric prefix ordering on pre/post stage hooks.
+
+When a stage has multiple hooks, run_hook sorts them alphabetically by name.
+To guarantee execution order, each hook name must start with a zero-padded
+numeric prefix (e.g. "01 Install operator", "02 Create site").
+
+This script checks:
+  - If a stage has >1 hook, every hook name starts with a numeric prefix.
+  - Prefixes are sequential (01, 02, 03, ...) with no gaps or duplicates.
+  - If a stage has exactly 1 hook, a prefix is allowed but not required.
+"""
+
+import pathlib
+import re
+import sys
+
+import yaml
+
+PREFIX_RE = re.compile(r'^(\d+)\s+')
+
+def validate_hooks(hooks, stage_label):
+    """Validate a list of hooks. Returns list of error strings."""
+    errors = []
+    if not hooks or len(hooks) < 2:
+        return errors
+
+    prefixes = []
+    for hook in hooks:
+        name = hook.get('name', '<unnamed>')
+        m = PREFIX_RE.match(name)
+        if not m:
+            errors.append(
+                f'{stage_label}: hook "{name}" is missing a numeric prefix '
+                f'(required when stage has {len(hooks)} hooks)'
+            )
+        else:
+            prefixes.append((int(m.group(1)), name))
+
+    if errors:
+        return errors
+
+    prefixes.sort(key=lambda x: x[0])
+    seen = set()
+    for num, name in prefixes:
+        if num in seen:
+            errors.append(
+                f'{stage_label}: duplicate prefix {num:02d} on hook "{name}"'
+            )
+        seen.add(num)
+
+    nums = [p[0] for p in prefixes]
+    expected = list(range(nums[0], nums[0] + len(nums)))
+    if nums != expected:
+        errors.append(
+            f'{stage_label}: prefixes {nums} are not sequential '
+            f'(expected {expected})'
+        )
+
+    return errors
+
+
+def validate_file(path):
+    """Validate all stages in one automation vars file."""
+    errors = []
+    with open(path) as fh:
+        content = yaml.safe_load(fh)
+
+    for scenario_name, scenario in content.get('vas', {}).items():
+        for i, stage in enumerate(scenario.get('stages', [])):
+            stage_name = stage.get('name', f'stage-{i}')
+            label = f'{path.name} > {scenario_name} > {stage_name}'
+
+            for hook_type in ('pre_stage_run', 'post_stage_run'):
+                hooks = stage.get(hook_type)
+                if hooks:
+                    errs = validate_hooks(hooks, f'{label} > {hook_type}')
+                    errors.extend(errs)
+
+    return errors
+
+
+def main():
+    src_dir = pathlib.Path(__file__).parent / '..' / 'automation' / 'vars'
+    all_errors = []
+
+    for f in sorted(src_dir.glob('*.yaml')):
+        all_errors.extend(validate_file(f))
+
+    if all_errors:
+        print('Hook ordering errors found:\n')
+        for err in all_errors:
+            print(f'  ERROR: {err}')
+        print(f'\n{len(all_errors)} error(s) found.')
+        sys.exit(1)
+    else:
+        print('All hook orderings are valid.')
+        sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

.github/workflows/automation-schema.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Run yamale
         run: yamale -s .ci/automation-schema.yaml automation/vars/
 
-  files_exist:
+  validate_automation:
     runs-on: ubuntu-latest
     needs:  # Ensure schema is valid before reading it
       - yamale
@@ -46,3 +46,6 @@ jobs:
 
       - name: Run file checker
         run: python3 .ci/validate-schema-paths.py
+
+      - name: Validate hook ordering
+        run: python3 .ci/validate-hook-ordering.py