Address sixth review: operator precedence, fan_in cleanup, registry resilience, docs

- Fix or/and operator precedence (or parsed first = lower precedence)
- Restore context.fan_in after fan-in step completes
- Catch JSONDecodeError in registry load for corrupted files
- Replace print() with on_step_start callback (library-safe)
- Gate validation warns when on_reject set but no reject option
- Shell step: document shell=True security tradeoff
- README: sdd-pipeline → speckit, parallel → sequential for fan-out
- ARCHITECTURE.md: parallel → fan-out/fan-in in diagram

Author: mnriem

src/specify_cli/__init__.py

@@ -4101,6 +4101,7 @@ def workflow_run(
 
     project_root = Path.cwd()
     engine = WorkflowEngine(project_root)
+    engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
 
     try:
         definition = engine.load_workflow(source)
@@ -4164,6 +4165,7 @@ def workflow_resume(
 
     project_root = Path.cwd()
     engine = WorkflowEngine(project_root)
+    engine.on_step_start = lambda sid, label: console.print(f"  \u25b8 [{sid}] {label} \u2026")
 
     try:
         state = engine.resume(run_id)

src/specify_cli/workflows/catalog.py

@@ -73,8 +73,12 @@ def __init__(self, project_root: Path) -> None:
     def _load(self) -> dict[str, Any]:
         """Load registry from disk or create default."""
         if self.registry_path.exists():
-            with open(self.registry_path, encoding="utf-8") as f:
-                return json.load(f)
+            try:
+                with open(self.registry_path, encoding="utf-8") as f:
+                    return json.load(f)
+            except (json.JSONDecodeError, ValueError):
+                # Corrupted registry file — reset to default
+                return {"schema_version": self.SCHEMA_VERSION, "workflows": {}}
         return {"schema_version": self.SCHEMA_VERSION, "workflows": {}}
 
     def save(self) -> None:

src/specify_cli/workflows/engine.py

@@ -297,6 +297,7 @@ class WorkflowEngine:
 
     def __init__(self, project_root: Path | None = None) -> None:
         self.project_root = project_root or Path(".")
+        self.on_step_start: Any = None  # Callable[[str, str], None] | None
 
     def load_workflow(self, source: str | Path) -> WorkflowDefinition:
         """Load a workflow from an installed ID or a local YAML path.
@@ -504,10 +505,11 @@ def _execute_steps(
                 {"event": "step_started", "step_id": step_id, "type": step_type}
             )
 
-            # Print progress so the user sees which step is running
-
+            # Log progress — use the engine's on_step_start callback if set,
+            # otherwise stay silent (library-safe default).
             label = step_config.get("command", "") or step_type
-            print(f"  ▸ [{step_id}] {label} …", flush=True)
+            if self.on_step_start is not None:
+                self.on_step_start(step_id, label)
 
             step_impl = registry.get(step_type)
             if not step_impl:

src/specify_cli/workflows/expressions.py

@@ -150,19 +150,20 @@ def _evaluate_simple_expression(expr: str, namespace: dict[str, Any]) -> Any:
     ):
         return expr[1:-1]
 
-    # Boolean operators
-    if " and " in expr:
-        parts = expr.split(" and ", 1)
-        left = _evaluate_simple_expression(parts[0].strip(), namespace)
-        right = _evaluate_simple_expression(parts[1].strip(), namespace)
-        return bool(left) and bool(right)
-
+    # Boolean operators — parse 'or' first (lower precedence) so that
+    # 'a or b and c' is evaluated as 'a or (b and c)'.
     if " or " in expr:
         parts = expr.split(" or ", 1)
         left = _evaluate_simple_expression(parts[0].strip(), namespace)
         right = _evaluate_simple_expression(parts[1].strip(), namespace)
         return bool(left) or bool(right)
 
+    if " and " in expr:
+        parts = expr.split(" and ", 1)
+        left = _evaluate_simple_expression(parts[0].strip(), namespace)
+        right = _evaluate_simple_expression(parts[1].strip(), namespace)
+        return bool(left) and bool(right)
+
     if expr.startswith("not "):
         inner = _evaluate_simple_expression(expr[4:].strip(), namespace)
         return not bool(inner)

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

@@ -27,6 +27,7 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             results.append(step_data.get("output", {}))
 
         # Resolve output expressions with fan_in in context
+        prev_fan_in = getattr(context, "fan_in", None)
         context.fan_in = {"results": results}
         resolved_output: dict[str, Any] = {"results": results}
 
@@ -36,6 +37,9 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
             else:
                 resolved_output[key] = expr
 
+        # Restore previous fan_in state
+        context.fan_in = prev_fan_in
+
         return StepResult(
             status=StepStatus.COMPLETED,
             output=resolved_output,

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

@@ -103,4 +103,11 @@ def validate(self, config: dict[str, Any]) -> list[str]:
                 f"Gate step {config.get('id', '?')!r}: 'on_reject' must be "
                 f"'abort', 'skip', or 'retry'."
             )
+        if on_reject in ("abort", "retry") and isinstance(options, list):
+            reject_choices = {"reject", "abort"}
+            if not any(o.lower() in reject_choices for o in options):
+                errors.append(
+                    f"Gate step {config.get('id', '?')!r}: on_reject={on_reject!r} "
+                    f"but options has no 'reject' or 'abort' choice."
+                )
         return errors

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

@@ -25,6 +25,10 @@ def execute(self, config: dict[str, Any], context: StepContext) -> StepResult:
 
         cwd = context.project_root or "."
 
+        # NOTE: shell=True is required to support pipes, redirects, and
+        # multi-command expressions in workflow YAML.  Workflow authors
+        # control commands; catalog-installed workflows should be reviewed
+        # before use (see PUBLISHING.md for security guidance).
         try:
             proc = subprocess.run(
                 run_cmd,

workflows/ARCHITECTURE.md

@@ -23,7 +23,7 @@ flowchart TD
     H -- "if" --> L["IfThenStep.execute()"]
     H -- switch --> M["SwitchStep.execute()"]
     H -- "while/do-while" --> N["Loop steps"]
-    H -- "fan-out/fan-in" --> O["Parallel steps"]
+    H -- "fan-out/fan-in" --> O["Fan-out/fan-in"]
 
     I --> P{Result status?}
     J --> P
@@ -198,7 +198,7 @@ src/specify_cli/
 │       ├── switch/          # Multi-branch dispatch
 │       ├── while_loop/      # While loop
 │       ├── do_while/        # Do-while loop
-│       ├── fan_out/         # Parallel dispatch
+│       ├── fan_out/         # Sequential per-item dispatch
 │       └── fan_in/          # Result aggregation
 └── __init__.py              # CLI commands: specify workflow run/resume/status/
                              #   list/add/remove/search/info,

workflows/README.md

@@ -32,10 +32,10 @@ For detailed architecture and internals, see [ARCHITECTURE.md](ARCHITECTURE.md).
 specify workflow search
 
 # Install a workflow from the catalog
-specify workflow add sdd-pipeline
+specify workflow add speckit
 
 # Run a workflow with inputs
-specify workflow run sdd-pipeline --input feature_name="user-auth"
+specify workflow run speckit --input feature_name="user-auth"
 
 # Check run status
 specify workflow status
@@ -44,19 +44,19 @@ specify workflow status
 specify workflow resume <run_id>
 
 # Get detailed workflow info
-specify workflow info sdd-pipeline
+specify workflow info speckit
 
 # Remove a workflow
-specify workflow remove sdd-pipeline
+specify workflow remove speckit
 ```
 
 ## Running Workflows
 
 ### From an Installed Workflow
 
 ```bash
-specify workflow add sdd-pipeline
-specify workflow run sdd-pipeline --input feature_name="user-auth"
+specify workflow add speckit
+specify workflow run speckit --input feature_name="user-auth"
 ```
 
 ### From a Local YAML File
@@ -68,7 +68,7 @@ specify workflow run ./my-workflow.yml --input feature_name="user-auth"
 ### Multiple Inputs
 
 ```bash
-specify workflow run sdd-pipeline \
+specify workflow run speckit \
   --input feature_name="user-auth" \
   --input scope="backend-only"
 ```
@@ -193,7 +193,7 @@ Execute steps at least once, then repeat while condition holds:
 
 ### Fan-Out Steps
 
-Parallel dispatch over a collection:
+Dispatch a step template for each item in a collection (sequential):
 
 ```yaml
 - id: parallel-impl
@@ -207,7 +207,7 @@ Parallel dispatch over a collection:
 
 ### Fan-In Steps
 
-Aggregate results from parallel steps:
+Aggregate results from fan-out steps:
 
 ```yaml
 - id: collect