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.

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.

• 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)

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.

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

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

┌─────────────────────────────────────────────────────────────┐
│ 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) │ │
│ └──────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘

1. 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

2. 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

3. 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)

4. 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

5. 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)

6. Repeat for native sw loop (~line 538):

   • Same guard + recall block
   • Append to goal/prompt before loop invocation
   • (Optional but preferred per issue)

7. Run targeted pipeline test:

   ./scripts/sw-pipeline-test.sh

   • Verify no test failures
   • Check for new failures vs. baseline

8. Run general test suite:

   npm test

   • Ensure no regressions
   • Confirm vitest all green

9. 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

10. Stage changes:

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

11. 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
    

12. Verify build & tests one final time:

    npm run build && npm test

• Task 1: Read pipeline-stages-build.sh and locate hive/fallback dispatch blocks
• Task 2: Review pattern in pipeline-stages-intake.sh (lines 374–400)
• Task 3: Verify ruflo_recall_similar_outcomes function signature in ruflo-adapter
• Task 4: Implement recall injection block before hive dispatch (~line 412)
• Task 5: Implement recall injection before single-agent fallback (~line 439)
• Task 6: Implement recall injection before native sw loop fallback (~line 538)
• Task 7: Add bounds check (head -c 2000) to prevent argv overflow
• Task 8: Add info log message when context injected
• Task 9: Run ./scripts/sw-pipeline-test.sh and verify no new failures
• Task 10: Run npm test and verify all tests pass
• Task 11: Verify npm run build succeeds
• Task 12: Stage changes and create commit with message
• Task 13: Verify git diff shows only expected changes (~15–45 lines depending on all 3 paths)

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

1. Run existing pipeline tests:

   ./scripts/sw-pipeline-test.sh 2>&1 | tail -30

   Baseline should show PASS/FAIL counts. After changes, no NEW failures.

2. Run full test suite:

   npm test

   Verify vitest passes, no regressions.

3. 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"

• Code Complete

  • All 3 injection paths implemented (hive, single-agent, native loop)
  • Guards use standard declare -f + ruflo_available pattern
  • Output bounded to 2000 chars with head -c 2000
  • Clear ## Historical Build Context header in appended text
  • Info log when context injected

• Tests Passing

  • ./scripts/sw-pipeline-test.sh passes (no new failures)
  • npm test passes (all tests green)
  • npm run build succeeds

• No Regressions

  • Existing hive behavior unchanged when ruflo unavailable
  • Goal string format compatible with existing hive invocation
  • No new dependencies introduced

• Code Review Ready

  • Diff shows only expected changes (recall injection blocks)
  • Commit message explains rationale and references #371
  • Comments explain guard conditions and bounds logic

• Acceptance Criteria Met

  • ruflo_recall_similar_outcomes called before hive dispatch
  • Result appended to enriched_goal with header
  • Guard + availability check in place
  • Never blocks pipeline (|| true)
  • Works when ruflo unavailable
  • Pipeline tests pass
  • Optional: single-agent + native loop fallbacks covered

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.

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

# 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

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)

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

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

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