Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

docs(workflows): correct filtered-count comparison guidance (#5148)

WOLIKIMCHENGf4a91f5e8c11
diff --git a/docs/reference/workflows.md b/docs/reference/workflows.md
index a24b700a2..cb4bc1fa9 100644
--- a/docs/reference/workflows.md
+++ b/docs/reference/workflows.md
@@ -1204,7 +1204,13 @@ Notes on the newer filters:
- **`to_json` output is deterministic.** Object keys are sorted and non-ASCII characters are left as-is rather than escaped, so the same value always serializes to the same bytes. That buys reproducibility only β€” it does **not** make the result safe to pass through a shell, because [interpolation adds no quoting or escaping](#interpolation-and-shell-safety). Do not interpolate unconstrained JSON into a `run` field.
- **`to_json` rejects non-finite floats.** `NaN`, `Infinity`, and `-Infinity` raise a `ValueError` naming `to_json` instead of serializing to bare tokens. None of the three is valid JSON, so emitting them would hand a standards-compliant downstream parser a string it must reject.
- **`to_json` requires string mapping keys.** JSON objects have string keys, so a mapping with any other key type β€” `{1: "a"}`, `{True: "a"}` β€” raises a `ValueError` naming the key type instead. Left to `json.dumps`, an integer key would be coerced to `"1"` and collide with an existing `"1"` key, while mixed key types would fail `sort_keys` with an ordering `TypeError` reported only as "not JSON-serializable".
-- **Trailing comparisons after a filter are rejected.** The parser splits on the top-level `|` before looking for operators, so `{{ items | length > 0 }}` raises rather than evaluating. The count does not exist until `length` runs, so there is no way to write that comparison; the supported branching form is the filter's own truthiness in a `condition:`, since `length` returns `0` for an empty input:
+- **Comparing filtered counts requires parentheses.** The parser splits on the top-level `|` before looking for operators, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises a `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:
+
+ ```yaml
+ condition: "{{ (inputs.items | length) >= 2 }}"
+ ```
+
+ For an emptiness check, use the filtered count's truthiness directly:
```yaml
condition: "{{ inputs.items | length }}" # 0 is False, any non-zero count is True
diff --git a/workflows/ARCHITECTURE.md b/workflows/ARCHITECTURE.md
index c06d28018..1ce065778 100644
--- a/workflows/ARCHITECTURE.md
+++ b/workflows/ARCHITECTURE.md
@@ -212,7 +212,13 @@ The older filters are more permissive and are unchanged: `join` stringifies unsu
**`to_json` output is deterministic.** It pins `sort_keys=True` and `ensure_ascii=False`, so the same value always serializes to the same bytes regardless of dict insertion order or platform, and non-ASCII text is not `\uXXXX`-escaped. This buys reproducibility only β€” it does **not** make the result safe to pass through a shell, because expression interpolation adds no quoting or escaping. See [Interpolation and shell safety](../docs/reference/workflows.md#interpolation-and-shell-safety) before interpolating JSON into a `run` field.
-**Filters and comparisons.** The parser splits on the top-level `|` before looking for operators, so a comparison or other trailing token after a filter is rejected as ambiguous rather than silently evaluated (`{{ items | default(0) > 5 }}` raises) β€” the same holds for the new filters. The count a `length` filter would produce does not exist before the filter runs, so there is no way to write `{{ items | length > 0 }}`; the only supported branching form is the filtered value's own truthiness in a `condition:`, since `length` returns `0` for an empty input:
+**Filters and comparisons.** The parser splits on the top-level `|` before looking for operators, so an unparenthesized trailing comparison such as `{{ inputs.items | length > 0 }}` raises a `ValueError`. Parenthesize the filtered operand to compare its result: `{{ (inputs.items | length) > 0 }}`. For a threshold of at least two:
+
+```yaml
+condition: "{{ (inputs.items | length) >= 2 }}"
+```
+
+For an emptiness check, use the filtered count's truthiness directly:
```yaml
condition: "{{ inputs.items | length }}" # 0 -> False, any non-zero count -> True