Fix: [Important] when: conditional field on steps for param-driven branching (#33) (#53)

* Fix: [Important] when: conditional field on steps for param-driven branching (#33)

The workflow format had no step-level conditional guard, which forced separate workflows for entry-point variants like resume and from-scratch. Adding `when` lets a step skip itself based on a Bash expression while keeping the workflow running.

Changes:
- Added `when` to the shared step base model with validation
- Rendered conditional skip guards in the generated harness
- Added parser, render, and end-to-end tests for `when`

Fixes #33

* Archive investigation for issue #33

* Fix: render when guards for nested steps (#33)

---------

Co-authored-by: OpenCode <opencode@localhost>

Author: tbrandenburg

.claude/PRPs/issues/completed/issue-33.md

@@ -0,0 +1,25 @@
+# Issue 33 Archive
+
+## Issue
+
+- #33: `[Important] when: conditional field on steps for param-driven branching`
+- Type: ENHANCEMENT
+
+## Investigation Summary
+
+The workflow model had no step-level conditional guard, so users had to duplicate whole workflows for entry-point variants like `--resume` and `--from-scratch`.
+
+## Implementation Plan
+
+- Add `when: str | None = None` to `BaseStep` in `src/flowsh_cli/models.py`
+- Validate `when` as a non-empty Bash expression string
+- Render a conditional skip guard in `src/flowsh_cli/render.py`
+- Add parser, render, and end-to-end tests in `tests/test_workflow_to_harness.py`
+
+## Validation
+
+- `make qa`
+
+## Notes
+
+The fix was implemented on branch `fix/issue-33-when-conditional-field`.

src/flowsh_cli/models.py

@@ -46,6 +46,7 @@ class StrictModel(BaseModel):
 
 class BaseStep(StrictModel):
     name: str | None = None
+    when: str | None = None
 
     @field_validator("name")
     @classmethod
@@ -56,6 +57,15 @@ def validate_optional_string(cls, value: str | None) -> str | None:
             raise ValueError("must not contain control characters")
         return value
 
+    @field_validator("when")
+    @classmethod
+    def validate_when(cls, value: str | None) -> str | None:
+        if value is not None and value.strip() == "":
+            raise ValueError("must not be empty")
+        if value is not None and has_unsafe_control_characters(value):
+            raise ValueError("must not contain unsafe control characters")
+        return value
+
 
 class BashStep(BaseStep):
     type: Literal["bash"]

src/flowsh_cli/render.py

@@ -241,7 +241,7 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
             inner_title = inner_step.name or default_step_title(i, inner_step)
             prefix_lines.append(section(f"For-inner step ({inner_step.type}): {inner_title}"))
             prefix_lines.append(f"{inner_fn}() {{")
-            prefix_lines.extend(_render_step_body(inner_step))
+            prefix_lines.extend(_render_step_body(inner_step, inner_title))
             prefix_lines.append("}")
             prefix_lines.append("")
 
@@ -259,7 +259,7 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
             child_fns.append(child_fn)
             prefix_lines.append(section(f"Parallel child {i} ({child.type}): {child_title}"))
             prefix_lines.append(f"{child_fn}() {{")
-            prefix_lines.extend(_render_step_body(child))
+            prefix_lines.extend(_render_step_body(child, child_title))
             prefix_lines.append("}")
             prefix_lines.append("")
 
@@ -271,23 +271,36 @@ def render_step(index: int, step: Step, used_function_names: set[str] | None = N
             body_lines.append(f'  wait "$pid_{child_fn}" || status=$?')
         body_lines.append('  return "$status"')
     else:
-        body_lines = _render_step_body(step)
+        body_lines = _render_step_body(step, title)
 
     runner = "run_stateful_step" if isinstance(step, (VarsStep, ForStep)) else "run_step"
     outer_lines = [
         section(f"Step {index} ({step.type}): {title}"),
         f"{function_name}() {{",
-        *body_lines,
-        "}",
-        f"{runner} {function_name}",
-        "",
     ]
+
+    outer_lines.extend(body_lines)
+    outer_lines.extend(
+        [
+            "}",
+            f"{runner} {function_name}",
+            "",
+        ]
+    )
     return prefix_lines + outer_lines
 
 
-def _render_step_body(step: Step) -> list[str]:
+def _render_step_body(step: Step, title: str) -> list[str]:
     """Return indented body lines for a step function (no wrapper, no run_step call)."""
     lines: list[str] = []
+
+    if step.when is not None:
+        lines.append(f"  if ! ({step.when}); then")
+        lines.append(f"    log INFO {bash_quote(f'Step skipped (when): {title}')}")
+        lines.append("    return 0")
+        lines.append("  fi")
+        lines.append("")
+
     if isinstance(step, VarsStep):
         lines.append("  local status=0")
         for name, command in step.values.items():