Epic: Implement native list iteration for DO_WHILE (Q4 Roadmap 2.3)

[nthmost-orkes]

DO_WHILE: Implement Native List Iteration

Context

DO_WHILE currently lacks a native list iteration mechanism, requiring developers to manually manage loop counters and implement complex index tracking logic. This makes iterating over collections unnecessarily difficult, creates verbose and error-prone workflow definitions, and requires understanding of expression language for array access. Native list iteration support would dramatically simplify common workflow patterns.

Current State vs. Desired State

Current:

• No native list iteration mechanism
• Developers manually manage loop counters and indices
• Complex, verbose workflow definitions for list iteration
• Error-prone index tracking logic
• Requires expression language knowledge for array access

Desired:

• Native items parameter for direct list iteration
• Automatic list traversal without manual counter management
• Iteration variables (loopItem, loopIndex) injected into context
• 50-70% LOC reduction for list iteration patterns
• Intuitive syntax familiar from programming languages

Technical Scope

What Needs to Be Implemented

• [ ] Add items parameter to DO_WHILE task definition for direct list iteration
• [ ] Implement automatic list traversal logic (iterate over array/collection)
• [ ] Inject iteration variables into loop context (current item and index)
• [ ] Support workflow expressions for items parameter
• [ ] Handle edge cases (empty list, null, non-list types)
• [ ] Maintain backward compatibility with existing counter-based loops
• [ ] Integrate with Phase 1 keepLastN cleanup parameter

Implementation Approach

Port list iteration support from Enterprise. Add items parameter to DO_WHILE task definition. Implement automatic traversal logic that injects current item and index into workflow context. Ensure backward compatibility with counter-based loops.

Files/Components Affected

• DoWhile.java (add list iteration logic ~60 lines)
• Task definition schema (add items parameter)
• Workflow context/variable injection mechanism
• Task validation logic

Dependencies

• Builds on Phase 1 DO_WHILE cleanup (#618) - list iteration must work with keepLastN
• No blocking dependencies

Related Issues

• Fixes #582 - DO_WHILE list iteration support
• Related to #583 - DO_WHILE enhancement

Success Criteria

• [ ] Workflow definitions reduced by 50-70% LOC for list iteration use cases
• [ ] items parameter accepts arrays and collections
• [ ] Current item accessible via workflow variable (e.g., ${loopItem})
• [ ] Current index accessible via workflow variable (e.g., ${loopIndex})
• [ ] Empty lists handled gracefully with zero iterations
• [ ] Backward compatibility maintained - counter-based loops work unchanged
• [ ] List iteration works correctly with Phase 1's keepLastN cleanup parameter
• [ ] Workflow expressions work in items parameter

Testing Requirements

• [ ] Unit tests for items parameter parsing
• [ ] Unit tests for list iteration logic
• [ ] Integration tests with various data types (arrays, collections, nested structures)
• [ ] Integration tests with workflow expressions in items parameter
• [ ] Performance tests with large lists (1000+ items)
• [ ] Backward compatibility verification for counter-based loops
• [ ] Integration testing with keepLastN cleanup from Phase 1
• [ ] Edge case tests (empty list, null, non-list types)

Documentation Needs

• [ ] Documentation for items parameter and list iteration
• [ ] Before/after examples showing LOC reduction
• [ ] Migration guide from counter-based to list iteration
• [ ] Common use case examples (batch processing, data transformation)
• [ ] Variable naming conventions (loopItem, loopIndex)
• [ ] Release notes highlighting list iteration support
• [ ] Best practices for list iteration patterns
• [ ] Integration guide with keepLastN cleanup parameter

Scope Notes

Backward Compatibility: Counter-based DO_WHILE loops must continue to work exactly as before. List iteration via items parameter is opt-in, ensuring zero breaking changes.

Variable Naming: Follow clear conventions (e.g., loopItem for current element, loopIndex for current index) to make iteration variables predictable and easy to use.

Phase 1 Integration: This builds on Phase 1's DO_WHILE cleanup feature. Ensure list iteration works correctly with keepLastN cleanup parameter - both features must work together seamlessly.

Developer Experience: List iteration is a fundamental pattern that should be intuitive. Good documentation with examples will drive adoption and showcase the improvement.