Skip to content

Pipeline Plan 414

Jump to bottom
ezigus edited this page Apr 23, 2026 · 2 revisions

Implementation Plan: Issue #414

Wire RUFLO_COST_BUDGET_MULTIPLIER into Hive Agent Counts

Executive Summary

This is a minimal, low-risk feature to wire the unused RUFLO_COST_BUDGET_MULTIPLIER config into three hive execution functions. The multiplier allows cost-aware agent scaling (e.g., 2.0 = double agents up to hard cap; 0.5 = half agents).

  • Scope: 1 file, 3 locations, ~7 lines per location
  • Complexity: Low — simple bash math with clamping
  • Risk: Minimal — fully backward-compatible (unset = no-op)
  • Dependencies: None — uses already-exported env var

Socratic Analysis

Requirements Clarity

What is the minimum viable change?

  • Add 7 lines of bash logic after each max_agents assignment in the 3 hive functions
  • Logic: if multiplier is set, apply it with clamping to [1, base_max]

Implicit requirements:

  • Multiplier must be optional (unset → current behavior preserved)
  • Result must clamp to [1, hard_cap] (prevent 0 agents or exceeding limit)
  • Handle floating-point multipliers (0.5, 2.0) safely using awk

Acceptance criteria:

  • ✅ RUFLO_COST_BUDGET_MULTIPLIER=2.0 scales up to hard cap
  • ✅ RUFLO_COST_BUDGET_MULTIPLIER=0.5 reduces by 50% (min 1)
  • ✅ Unset multiplier = current behavior (backward compatible)
  • ✅ scripts/sw-ruflo-adapter-test.sh passes
  • ✅ npm test passes

Design Alternatives

Alternative Pros Cons Blast Radius Choice
1. Inline logic (Recommended) Minimal, localized, matches issue spec 3× code duplication Tiny ✅ CHOSEN
2. Helper function DRY, testable, maintainable Adds function overhead Small —
3. Config-driven Flexible, future-proof Overkill, scope creep Large —

Rationale for Alternative 1: Simplest approach, exactly matches issue specification, minimal code duplication is acceptable for ~7 lines of straightforward bash.

Risk Assessment

Risk Mitigation
Agent count → 0 Clamp to min 1: (v<1?1:v) in awk
Invalid multiplier value Fallback to original: || echo "$max_agents"
Exceeds hard cap Clamp to max: (v>d?d:v) in awk
Breaks backward compat Guard: [[ -n "${RUFLO_COST_BUDGET_MULTIPLIER:-}" ]]
Insufficient tests Add 5 new test cases covering edge cases

Dependency Analysis

Depends on:

  • RUFLO_COST_BUDGET_MULTIPLIER (already exported at line 138)
  • awk (standard on all platforms)
  • Bash parameter expansion (standard)

Depended on by:

  • Callers of ruflo_execute_review(), ruflo_execute_quality(), ruflo_execute_audit()
  • Pipeline stages: review, compound_quality, audit

Circular dependencies: None — pure config → behavior flow.

Simplicity Check

Can be simpler? No — logic is already minimal (one if + one awk). Reuse infrastructure? Yes — using already-exported env var. Simpler approach work? No — needs clamping for edge cases.

Implementation Specification

Files to Modify

File Locations Change Type
scripts/lib/ruflo-adapter.sh Lines 816, 961, 1069 Modify (add ~7 lines each)
scripts/sw-ruflo-adapter-test.sh After line 1633 Add (5 new test cases)

The Code Pattern (for all 3 locations)

# After the max_agents/cq_agents assignment:
if [[ -n "${RUFLO_COST_BUDGET_MULTIPLIER:-}" ]]; then
    local _default_max="$max_agents"
    max_agents=$(awk -v d="$_default_max" -v m="${RUFLO_COST_BUDGET_MULTIPLIER}" \
        'BEGIN{v=int(d*m); print (v<1?1:(v>d?d:v))}' 2>/dev/null || echo "$max_agents")
fi

Semantic: clamped_agents = max(1, min(base_max, floor(base_max × multiplier)))

Implementation Steps

Step 1: Modify ruflo_execute_review() (line 816)

  • Insert multiplier logic after line 816 (local max_agents=...)
  • Variable: max_agents

Step 2: Modify ruflo_execute_quality() (line 961)

  • Insert multiplier logic after line 961 (local cq_agents=...)
  • Variable: cq_agents (note: different variable name)

Step 3: Modify ruflo_execute_audit() (line 1069)

  • Insert multiplier logic after line 1069 (local max_agents=...)
  • Variable: max_agents

Step 4: Add test for multiplier=2.0 (scales up)

  • Set RUFLO_COST_BUDGET_MULTIPLIER=2.0, RUFLO_MAX_AGENTS=2
  • Expect: agent count scales to hard cap (e.g., 4)

Step 5: Add test for multiplier=0.5 (scales down)

  • Set RUFLO_COST_BUDGET_MULTIPLIER=0.5, RUFLO_MAX_AGENTS=10
  • Expect: agent count = 5

Step 6: Add test for multiplier=0.1 (clamps min)

  • Set RUFLO_COST_BUDGET_MULTIPLIER=0.1, RUFLO_MAX_AGENTS=10
  • Expect: agent count = 1 (clamped)

Step 7: Add test for invalid multiplier (fallback)

  • Set RUFLO_COST_BUDGET_MULTIPLIER="invalid", RUFLO_MAX_AGENTS=4
  • Expect: agent count = 4 (fallback)

Step 8: Add test for unset multiplier (backward compatibility)

  • Unset RUFLO_COST_BUDGET_MULTIPLIER, RUFLO_MAX_AGENTS=4
  • Expect: agent count = 4 (unchanged)

Step 9: Run unit tests

  • Execute: scripts/sw-ruflo-adapter-test.sh
  • Verify: all tests pass (existing + new)

Step 10: Run full test suite

  • Execute: npm test
  • Verify: no regressions in other modules

Task Checklist

  • Task 1: Add multiplier logic to ruflo_execute_review() after line 816
  • Task 2: Add multiplier logic to ruflo_execute_quality() after line 961 (note: use cq_agents variable)
  • Task 3: Add multiplier logic to ruflo_execute_audit() after line 1069
  • Task 4: Add test case for multiplier=2.0 (scale up)
  • Task 5: Add test case for multiplier=0.5 (scale down)
  • Task 6: Add test case for multiplier=0.1 (clamp to min)
  • Task 7: Add test case for multiplier=invalid (fallback)
  • Task 8: Add test case for unset multiplier (backward compat)
  • Task 9: Run unit test suite (scripts/sw-ruflo-adapter-test.sh)
  • Task 10: Run full test suite (npm test)
  • Task 11: Verify backward compatibility (no multiplier set)
  • Task 12: Commit changes with issue reference

Testing Approach

Unit Testing

  1. Execute scripts/sw-ruflo-adapter-test.sh
  2. All 5 new tests + existing tests must pass
  3. Verify no existing tests are broken

Integration Testing

  1. Execute npm test (full suite)
  2. Verify no regressions in other modules

Manual Verification

# Test 1: Scale up
export RUFLO_COST_BUDGET_MULTIPLIER=2.0 RUFLO_MAX_AGENTS=2
scripts/sw-ruflo-adapter-test.sh

# Test 2: Scale down
export RUFLO_COST_BUDGET_MULTIPLIER=0.5 RUFLO_MAX_AGENTS=10
scripts/sw-ruflo-adapter-test.sh

# Test 3: Backward compatibility
unset RUFLO_COST_BUDGET_MULTIPLIER
export RUFLO_MAX_AGENTS=4
scripts/sw-ruflo-adapter-test.sh

Definition of Done

  • All 3 functions modified with multiplier logic
  • All 5 new test cases added and passing
  • Unit test suite passes: scripts/sw-ruflo-adapter-test.sh
  • Full test suite passes: npm test
  • No regressions in existing functionality
  • Multiplier=2.0 scales agents up to hard cap ✓
  • Multiplier=0.5 reduces agents by 50% ✓
  • Multiplier=0.1 clamps to min 1 agent ✓
  • Invalid multiplier gracefully ignored ✓
  • Unset multiplier preserves backward compatibility ✓
  • Commit message references issue #414
  • Branch ready for PR/review

Summary

Approach: Add 7-line multiplier logic to each of the 3 hive execution functions, with clamping to [1, hard_cap]. Fully backward-compatible (unset multiplier = no-op).

Files: 2 files, ~40 lines total (code + tests)

Risk: Minimal — env-var driven, no new dependencies, backward-compatible

Effort: ~30 minutes (code + tests + validation)

Clone this wiki locally