|
| 1 | +# Downstream Modernization: BMW, Ratchet, Ratchet-CLI |
| 2 | + |
| 3 | +**Date:** 2026-03-11 |
| 4 | +**Status:** Approved |
| 5 | + |
| 6 | +## Goal |
| 7 | + |
| 8 | +Ensure BMW, ratchet, and ratchet-cli take advantage of workflow engine improvements from v0.3.18 → v0.3.32 and modular v1.12.0 → v1.12.3. |
| 9 | + |
| 10 | +## Changes |
| 11 | + |
| 12 | +### 1. wfctl modernize --apply (BMW + Ratchet) |
| 13 | + |
| 14 | +Run automated YAML fixes on both projects: |
| 15 | + |
| 16 | +**BMW** (`buymywishlist-phase3/app.yaml`): ~364 issues |
| 17 | +- 305 hyphen-step names → underscore |
| 18 | +- ~40 `parse_body: true` → remove (body auto-parsed since v0.3.28) |
| 19 | +- 1 conditional-field using template syntax → dot-path |
| 20 | +- 2 camelCase config violations |
| 21 | + |
| 22 | +**Ratchet** (`ratchet/config/*.yaml`): ~230+ issues |
| 23 | +- 228 hyphen-step names → underscore |
| 24 | +- 28 `parse_body: true` → remove |
| 25 | +- 5 camelCase config violations |
| 26 | + |
| 27 | +### 2. step.parallel Adoption |
| 28 | + |
| 29 | +**BMW pipelines** (6-8 candidates): |
| 30 | +- `user-dashboard`: parallelize count_wishlists + count_contributions |
| 31 | +- `analytics-overview`: parallelize check_permission + fetch_stats |
| 32 | +- `analytics-wishlists`: parallelize check_permission + fetch_stats |
| 33 | +- `analytics-contributions`: parallelize check_permission + fetch_stats |
| 34 | +- `analytics-revenue`: parallelize check_permission + fetch_revenue |
| 35 | +- `payment-create-intent`: parallelize check_mock_mode + get_tenant_settings |
| 36 | +- `admin-users-list`: parallelize fetch_role + fetch_users |
| 37 | +- `admin-audit-logs`: parallelize fetch_role + fetch_logs |
| 38 | + |
| 39 | +**Ratchet** (1 candidate): |
| 40 | +- `/api/info` route: parallelize get-started-at + count-agents + count-teams (3 independent queries) |
| 41 | + |
| 42 | +### 3. Execution Tracing Configuration |
| 43 | + |
| 44 | +**BMW:** |
| 45 | +- Add `X-Workflow-Trace` to CORS allowedHeaders |
| 46 | +- Already has observability.otel + http.middleware.otel configured |
| 47 | + |
| 48 | +**Ratchet:** |
| 49 | +- Add `X-Workflow-Trace` to CORS allowedHeaders (if CORS configured) |
| 50 | +- Already has observability.otel configured |
| 51 | + |
| 52 | +### Out of Scope |
| 53 | + |
| 54 | +- `ratchet modernize` CLI command (ratchet-cli is an AI agent client, not a workflow toolchain) |
| 55 | +- step.hash for bcrypt (only supports MD5/SHA256/SHA512) |
| 56 | +- Collection template functions replacing SQL aggregation (SQL is more efficient) |
| 57 | +- step.cli_print/cli_invoke for ratchet-cli (uses Bubbletea TUI) |
| 58 | +- Actor model (no current use case) |
| 59 | + |
| 60 | +## Implementation Plan |
| 61 | + |
| 62 | +### Phase 1: Automated YAML Modernization |
| 63 | +1. Run `wfctl modernize --apply` on BMW app.yaml |
| 64 | +2. Run `wfctl modernize --apply` on ratchet config/*.yaml |
| 65 | +3. Verify configs still parse correctly |
| 66 | +4. Commit changes |
| 67 | + |
| 68 | +### Phase 2: step.parallel Adoption |
| 69 | +1. BMW: Refactor 6-8 pipelines to use step.parallel for independent queries |
| 70 | +2. Ratchet: Refactor /api/info route to use step.parallel |
| 71 | +3. Update template references to access parallel step outputs |
| 72 | +4. Commit changes |
| 73 | + |
| 74 | +### Phase 3: Execution Tracing |
| 75 | +1. Add X-Workflow-Trace to CORS headers in both projects |
| 76 | +2. Commit changes |
| 77 | + |
| 78 | +### Phase 4: Verify and Push |
| 79 | +1. Run wfctl validate on all configs |
| 80 | +2. Push all changes |
0 commit comments