Address fifteenth review: fan_in docstring, gate defaults, validation guards, reserved prefix

- FanInStep docstring: aggregate-only, no blocking semantics
- FanInStep: guard output_config as dict, handle None
- Gate validate: use same default options as execute
- Validate inputs is dict and steps is list before iterating
- Reserve _fanout_ prefix in step ID validation
- PUBLISHING.md: remove unenforced checklist items, add _fanout_ note

Author: mnriem

src/specify_cli/workflows/engine.py

@@ -115,18 +115,24 @@ def validate_workflow(definition: WorkflowDefinition) -> list[str]:
         errors.append("Workflow is missing 'workflow.version'.")
 
     # -- Inputs -----------------------------------------------------------
-    for input_name, input_def in definition.inputs.items():
-        if not isinstance(input_def, dict):
-            errors.append(f"Input {input_name!r} must be a mapping.")
-            continue
-        input_type = input_def.get("type")
-        if input_type and input_type not in ("string", "number", "boolean"):
-            errors.append(
-                f"Input {input_name!r} has invalid type {input_type!r}. "
-                f"Must be 'string', 'number', or 'boolean'."
-            )
+    if not isinstance(definition.inputs, dict):
+        errors.append("'inputs' must be a mapping (or omitted).")
+    else:
+        for input_name, input_def in definition.inputs.items():
+            if not isinstance(input_def, dict):
+                errors.append(f"Input {input_name!r} must be a mapping.")
+                continue
+            input_type = input_def.get("type")
+            if input_type and input_type not in ("string", "number", "boolean"):
+                errors.append(
+                    f"Input {input_name!r} has invalid type {input_type!r}. "
+                    f"Must be 'string', 'number', or 'boolean'."
+                )
 
     # -- Steps ------------------------------------------------------------
+    if not isinstance(definition.steps, list):
+        errors.append("'steps' must be a list.")
+        return errors
     if not definition.steps:
         errors.append("Workflow has no steps defined.")
 
@@ -154,6 +160,11 @@ def _validate_steps(
             errors.append("Step is missing 'id' field.")
             continue
 
+        if step_id.startswith("_fanout_"):
+            errors.append(
+                f"Step ID {step_id!r} uses reserved prefix '_fanout_'."
+            )
+
         if step_id in seen_ids:
             errors.append(f"Duplicate step ID {step_id!r}.")
         seen_ids.add(step_id)

src/specify_cli/workflows/steps/fan_in/__init__.py

@@ -9,16 +9,20 @@
 
 
 class FanInStep(StepBase):
-    """Join point — blocks until all ``wait_for:`` steps complete.
+    """Join point that aggregates results from ``wait_for:`` steps.
 
-    Aggregates their results into ``fan_in.results``.
+    Reads completed step outputs from ``context.steps`` and collects
+    them into ``output.results``.  Does not block; relies on the
+    engine executing steps sequentially.
     """
 
     type_key = "fan-in"
 
     def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
         wait_for = config.get("wait_for", [])
-        output_config = config.get("output", {})
+        output_config = config.get("output") or {}
+        if not isinstance(output_config, dict):
+            output_config = {}
 
         # Collect results from referenced steps
         results = []

src/specify_cli/workflows/steps/gate/__init__.py

@@ -92,8 +92,8 @@ def validate(self, config: dict[str, Any]) -> list[str]:
             errors.append(
                 f"Gate step {config.get('id', '?')!r} is missing 'message' field."
             )
-        options = config.get("options", [])
-        if options and not isinstance(options, list):
+        options = config.get("options", ["approve", "reject"])
+        if not isinstance(options, list):
             errors.append(
                 f"Gate step {config.get('id', '?')!r}: 'options' must be a list."
             )

workflows/PUBLISHING.md

@@ -93,8 +93,7 @@ steps:
 - ✅ Step types are valid: `command`, `prompt`, `shell`, `gate`, `if`, `switch`, `while`, `do-while`, `fan-out`, `fan-in`
 - ✅ Required fields present per step type (e.g., `condition` for `if`, `expression` for `switch`)
 - ✅ Input types are valid: `string`, `number`, `boolean`
-- ✅ Enum values match declared type
-- ✅ Expression references (`{{ steps.*.output.* }}`) point to steps that run before they're referenced
+- ✅ Step IDs do not start with `_fanout_` (reserved prefix)
 
 ### 3. Test Locally