Pipeline Plan 371

Implementation Plan: feat(ruflo): inject ruflo_recall_similar_outcomes into stage_build

Executive Summary

This feature adds historical context to the build hive by recalling similar past outcomes before initialization. The change is minimal (single code block, ~15 lines), follows existing patterns from stage_plan and stage_design, and requires modifications to only one file. Zero breaking changes to function signatures or existing code paths.

Requirements Analysis

What This Solves

Currently, stage_build() launches the hive with a goal string containing plan/design context but no historical signal about how similar issues were built. This feature pre-seeds the goal with vector-search results from ruflo memory, giving hive agents a probabilistic starting point based on past outcomes.

Acceptance Criteria (from issue)

ruflo_recall_similar_outcomes called before ruflo_execute_build_hive
Result appended to enriched_goal under ## Historical Build Context header
Guard uses standard availability check (declare -f + ruflo_available)
Call uses || true — never blocks pipeline
Works when ruflo unavailable (enriched_goal unchanged)
Passes ./scripts/sw-pipeline-test.sh and npm test
Single-agent fallback path also receives recall context (optional but preferred)

Design Decision Analysis

Alternative 1: Append to enriched_goal (✅ RECOMMENDED)

Pros:

Matches existing pattern from stage_plan/stage_design
Minimal code footprint (~15 lines)
No function signature changes
Goal string already supports injection
Safe to merge independently

Cons:

Goal string grows (mitigated by 2000-char cap mentioned in issue)
Hive sees context as text, not structured data

Trade-off: Simplicity + low blast radius vs. structured data handling. Justifies choice: We're optimizing for safety and maintainability over theoretical purity.

Alternative 2: Inject as separate parameter to ruflo_execute_build_hive()

Pros:

Cleaner separation of concerns
More structured data passing

Cons:

Requires modifying function signature in ruflo-adapter.sh
Breaks existing callers if not updated everywhere
Issue explicitly forbids modifying ruflo_execute_build_hive()
Larger blast radius

Verdict: ❌ REJECTED — Issue constraint + higher risk

Alternative 3: Pre-process goal in enriched_goal creation step

Pros:

Earlier in pipeline, before any branching

Cons:

Spreads logic across multiple stages
Harder to test in isolation
Goal enrichment becomes implicit

Verdict: ❌ REJECTED — Less maintainable, requires touching multiple stages

Risk Assessment

Risk	Impact	Likelihood	Mitigation
argv overflow	Goal string exceeds shell limits	Low	Cap output at 2000 chars with `head -c 2000`
ruflo unavailable	Guard fails, goal unmodified	Medium	`declare -f` + `ruflo_available` check + `\|\| true`
Namespace mismatch	Recall searches wrong memory	Low	Use consistent namespace (from memory hints: `learning-<repo_hash>`)
Silent failure	Recall fails, no visibility	Medium	Add `info` log when context injected; use `2>/dev/null` safely
Performance regression	Recall adds latency	Low	Non-blocking call, pipeline continues regardless, issue notes #313 blocks real benefit
Breaking hive behavior	Context confuses hive agents	Low	Append after existing goal, use clear `## Historical Build Context` header

Component Decomposition

┌─────────────────────────────────────────────────────────────┐
│ stage_build() - Main Pipeline Stage                         │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Guard Layer (NEW)                                    │   │
│  │ • declare -f ruflo_recall_similar_outcomes           │   │
│  │ • declare -f ruflo_available                         │   │
│  │ • ruflo_available check                              │   │
│  └──────────────────────────────────────────────────────┘   │
│                    ↓                                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Goal Enhancement Layer (NEW)                         │   │
│  │ • Call: ruflo_recall_similar_outcomes(...)           │   │
│  │ • Capture: _ruflo_build_ctx                          │   │
│  │ • Bound: head -c 2000 (safety)                       │   │
│  └──────────────────────────────────────────────────────┘   │
│                    ↓                                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Append Integration (NEW)                             │   │
│  │ • enriched_goal += context header + _ruflo_build_ctx │   │
│  │ • Info log: bytes appended                           │   │
│  └──────────────────────────────────────────────────────┘   │
│                    ↓                                          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │ Hive Dispatch (EXISTING)                             │   │
│  │ • ruflo_execute_build_hive "$enriched_goal"          │   │
│  │  (now receives updated goal with context)            │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Files to Modify

File	Purpose	Changes
`scripts/lib/pipeline-stages-build.sh`	Primary implementation	Add recall injection block before hive dispatch (~line 412), before single-agent fallback (~line 439), and before native loop fallback (~line 538)
`scripts/sw-pipeline-test.sh`	Verification	Ensure tests pass (no modifications required unless new tests needed)
`npm test`	General tests	Verify no regressions

Implementation Steps

Phase 1: Analyze Current Code (Non-Blocking)

Read scripts/lib/pipeline-stages-build.sh to locate:
- Hive dispatch block (~line 412)
- Single-agent fallback (~line 439)
- Native sw loop fallback (~line 538)
- Current enriched_goal construction
Review scripts/lib/pipeline-stages-intake.sh (lines 374–400) to copy pattern:
- Guard structure: declare -f + ruflo_available
- Variable naming: _ruflo_*_ctx
- Append structure: \n\n## Header\n${var}
- Info logging
Verify ruflo functions exist:
- Check scripts/lib/ruflo-adapter.sh for ruflo_recall_similar_outcomes signature
- Confirm it accepts: issue_type and labels parameters
- Confirm it returns plain text (not JSON, per memory)

Phase 2: Implement Recall Injection (15 lines of code)

Insert before hive dispatch block (~line 412 in pipeline-stages-build.sh):

# Ruflo: recall similar build outcomes to seed the hive goal
if declare -f ruflo_recall_similar_outcomes >/dev/null 2>&1 && \
   declare -f ruflo_available >/dev/null 2>&1 && \
   ruflo_available; then
    local _ruflo_build_ctx
    _ruflo_build_ctx=$(ruflo_recall_similar_outcomes \
        "${INTELLIGENCE_ISSUE_TYPE:-backend}" "${ISSUE_LABELS:-}" 2>/dev/null || true)
    if [[ -n "$_ruflo_build_ctx" ]]; then
        # Bound to 2000 chars to prevent argv overflow
        _ruflo_build_ctx=$(printf '%.2000s' "$_ruflo_build_ctx")
        enriched_goal="${enriched_goal}

## Historical Build Context (from ruflo memory)
${_ruflo_build_ctx}"
        info "Ruflo build context injected into hive goal (${#_ruflo_build_ctx} bytes)"
    fi
fi

Repeat for single-agent fallback (~line 439):
- Same guard + recall block
- Append to enriched_goal before ruflo_execute_build call
- (Optional but preferred per issue)
Repeat for native sw loop (~line 538):
- Same guard + recall block
- Append to goal/prompt before loop invocation
- (Optional but preferred per issue)

Phase 3: Testing & Verification

Run targeted pipeline test:
```
./scripts/sw-pipeline-test.sh
```
- Verify no test failures
- Check for new failures vs. baseline
Run general test suite:
```
npm test
```
- Ensure no regressions
- Confirm vitest all green
Manual smoke test (optional):
- Mock ruflo_recall_similar_outcomes in a test env
- Verify enriched_goal contains injected context
- Verify guard works when function missing

Phase 4: Commit & Document

Stage changes:

git add scripts/lib/pipeline-stages-build.sh

Create commit:

feat(ruflo): inject ruflo_recall_similar_outcomes into stage_build

- Recall similar build outcomes before hive dispatch
- Append context to enriched_goal under "## Historical Build Context"
- Applied to hive path, single-agent fallback, native loop fallback
- Guards against missing/unavailable ruflo (|| true, no blocking)
- Bounds output to 2000 chars to prevent argv overflow
- Follows pattern from stage_plan/stage_design in stage_intake.sh

Fixes #371

Verify build & tests one final time:
```
npm run build && npm test
```

Task Checklist

Testing Approach

Test Strategy (Pyramid)

Unit Tests:

Mock ruflo_recall_similar_outcomes to return fixed context string
Verify enriched_goal variable is updated correctly
Verify guard checks all conditions (declare -f, ruflo_available, non-empty result)
Test bounds: output > 2000 chars is truncated

Integration Tests:

Full pipeline test with real/mocked hive
Verify hive receives updated goal with context header
Verify fallback paths (single-agent, native loop) also get context

Edge Cases:

ruflo_available() returns false → goal unchanged
ruflo_recall_similar_outcomes function missing → goal unchanged
Recall returns empty string → goal unchanged
Recall returns > 2000 chars → truncated to 2000

Test Execution Plan

Run existing pipeline tests:
```
./scripts/sw-pipeline-test.sh 2>&1 | tail -30
```
Baseline should show PASS/FAIL counts. After changes, no NEW failures.
Run full test suite:
```
npm test
```
Verify vitest passes, no regressions.

Optionally add shell unit test in scripts/sw-pipeline-test.sh:

# Test: enriched_goal is updated with ruflo context
# Mock: ruflo_recall_similar_outcomes returns "past outcome: X"
# Assert: enriched_goal contains "## Historical Build Context"

Definition of Done

Architecture Decision Record (ADR-#371)

Context

The hive-mind build stage lacks historical context about similar past builds. Agents operate blind, re-solving problems that have been solved before. Ruflo memory stores vector-indexed outcomes; recalling before hive dispatch seeds the goal with probabilistic guidance.

Decision

Inject ruflo_recall_similar_outcomes before hive dispatch, appending result to enriched_goal string.

Interface Contract

# Input
enriched_goal="<plan/design context>"
INTELLIGENCE_ISSUE_TYPE="backend"  # From intake context
ISSUE_LABELS="bug,urgent"          # From intake context

# Recall invocation (guarded)
if declare -f ruflo_recall_similar_outcomes >/dev/null 2>&1 && \
   declare -f ruflo_available >/dev/null 2>&1 && \
   ruflo_available; then
    _ruflo_build_ctx=$(ruflo_recall_similar_outcomes \
        "${INTELLIGENCE_ISSUE_TYPE:-backend}" "${ISSUE_LABELS:-}" 2>/dev/null || true)
fi

# Output
enriched_goal="<original> + \n\n## Historical Build Context\n<context>"
# Consumed by: ruflo_execute_build_hive "$enriched_goal"

Error Handling:

Function missing: Guard skips, goal unchanged
Recall fails: 2>/dev/null || true captures error, goal unchanged
Empty result: [[ -n "$_ruflo_build_ctx" ]] skips append, goal unchanged
Overflow: head -c 2000 prevents argv limits

Alternatives Considered

Alternative	Why Not Chosen
Separate parameter to hive function	Issue forbids modifying `ruflo_execute_build_hive()`; larger blast radius
Pre-process in goal enrichment step	Spreads logic across stages; harder to test; makes goal construction implicit
Store context in temp file, pass path	Over-engineering for bash; goal string already works fine

Consequences

Positive:

Hive agents see historical patterns during planning
Zero impact if ruflo unavailable (safe fallback)
Minimal code (follows existing stage_plan pattern)
Independent of #313; can merge now

Negative:

Goal string length increases (mitigated: 2000-char bound)
Hive interprets context as text, not structured data (acceptable: agents are LLMs)
Real performance benefit blocked on #313 (memory persistence)

Data Flow

intake stage creates: enriched_goal, INTELLIGENCE_ISSUE_TYPE, ISSUE_LABELS
                           ↓
plan stage appends plan context to enriched_goal
                           ↓
design stage appends design context to enriched_goal
                           ↓
build stage:
  1. Guard check (function exists, ruflo available)
  2. Recall: ruflo_recall_similar_outcomes(issue_type, labels)
  3. Append: enriched_goal += "\n\n## Historical Build Context\n" + recall_result
  4. Dispatch: ruflo_execute_build_hive("$enriched_goal")
                           ↓
hive agents see full context (plan + design + history) in prompt

Success Metrics

Acceptance Criteria: All 6 items from issue satisfied ✓
Test Coverage: ./scripts/sw-pipeline-test.sh + npm test pass ✓
Regression Proof: No behavior change when ruflo unavailable ✓
Code Simplicity: Single file, ~15–45 lines depending on 3 paths ✓
Pattern Consistency: Matches stage_plan/stage_design injections ✓

Next Steps (After Implementation)

Merge this PR to unblock pipeline
Implement #313 (CI memory persistence) to realize full value
Monitor hive performance with historical context enabled
Add telemetry: track how often recall context is used vs. ignored

Pipeline Plan 371

Implementation Plan: feat(ruflo): inject ruflo_recall_similar_outcomes into stage_build

Executive Summary

Requirements Analysis

What This Solves

Acceptance Criteria (from issue)

Design Decision Analysis

Alternative 1: Append to enriched_goal (✅ RECOMMENDED)

Alternative 2: Inject as separate parameter to ruflo_execute_build_hive()

Alternative 3: Pre-process goal in enriched_goal creation step

Risk Assessment

Component Decomposition

Files to Modify

Implementation Steps

Phase 1: Analyze Current Code (Non-Blocking)

Phase 2: Implement Recall Injection (15 lines of code)

Phase 3: Testing & Verification

Phase 4: Commit & Document

Task Checklist

Testing Approach

Test Strategy (Pyramid)

Test Execution Plan

Definition of Done

Architecture Decision Record (ADR-#371)

Context

Decision

Interface Contract

Alternatives Considered

Consequences

Data Flow

Success Metrics

Next Steps (After Implementation)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!