Pipeline Plan 325

Now I have enough context. Let me create a detailed implementation plan for this feature.

Implementation Plan: Integrate Audit Stage with Ruflo Hive-Mind Specialist Security Agents

Files to Modify

1. scripts/lib/ruflo-adapter.sh — Add ruflo_execute_audit() function
2. scripts/lib/pipeline-stages-review.sh — Call ruflo_execute_audit() from stage_audit()
3. config/event-schema.json — Register audit events
4. scripts/sw-ruflo-adapter-test.sh — Add tests for audit hive

---

Requirements Analysis (Pre-Coding)

Alternatives Considered

1. Hive-based parallel audit (chosen) ✓

   • Matches existing review/CQ pattern
   • Proven infrastructure with specialist agents
   • Security agents can operate in parallel: CVE scanner → secrets detector → OWASP auditor → compliance checker
   • Blast radius: Low (new function only, fail-open fallback)
   • Complexity: Medium (replicates existing pattern exactly)

2. Sequential agent passes

   • Simpler but loses parallelism benefit
   • Longer execution time
   • Inconsistent with review/CQ stages

3. Single-agent threat model analyzer

   • Too narrow scope
   • Misses multi-perspective security analysis

Decision: Hive-based approach is clear winner — replicates proven pattern.

Root Cause Analysis (Why Audit Was Missed)

The issue states: "It was missed in the original series, not intentionally deferred." The audit stage was implemented with sequential CLI checks while review/CQ received parallel hive treatment. This is a straightforward backfill task.

Edge Cases Identified

1. Ruflo unavailable → Fail-open, native audit continues
2. Hive spawn partial failure → Proceed with fewer agents (non-fatal)
3. ADR namespace missing → Skip context injection, audit continues
4. Findings aggregation → Union (same as review — additive not consensus)
5. Timeout → Circuit-breaker disables ruflo for remainder (same as review)

---

Implementation Steps

Phase 1: Add ruflo_execute_audit() to ruflo-adapter.sh (Lines ~900-1050)

Pattern (identical structure to ruflo_execute_review):

1. Check ruflo_available
2. Validate inputs (diff_content, artifact_file)
3. Resolve pipeline ID and namespace
4. Emit ruflo.audit_start event
5. Optionally route for dynamic agent count via hooks route
6. Initialize hive (hierarchical topology)
7. Spawn specialist agents (cve_scanner, secrets_detector, owasp_auditor, compliance_checker)
8. Store audit scope in shared memory (bounded to 8000 bytes)
9. Inject ADR context from prior design stage (same as review)
10. NEW: Read prior review findings from pipeline-<PIPELINE_ID> namespace for context
11. Orchestrate parallel audit (mode: "audit", 20 max-turns)
12. Aggregate findings via union (list namespace)
13. Shutdown hive (always, even on failure)
14. Write findings to artifact file
15. Persist audit result to pipeline-<PIPELINE_ID> for downstream stages (audit, pr)
16. Emit ruflo.audit_complete event
17. Return 0 on success, 1 on hive failure

Key Differences from Review:

• Event names: ruflo.audit_* instead of ruflo.review_*
• Namespace: hive-audit-<PIPELINE_ID> instead of hive-review-<PIPELINE_ID>
• Orchestration goal: "parallel security audit: CVE, secrets, OWASP, compliance in namespace hive-audit-<PIPELINE_ID>"
• Reads FROM pipeline-<PIPELINE_ID> (review findings) rather than just storing to it
• Max-turns: 20 (same as review)
• Timeout: 300s (same as review)

Phase 2: Update stage_audit() in pipeline-stages-review.sh (Lines ~651-775)

Before existing sequential checks:

# Ruflo parallel security audit hive — runs before native audit checks
# Fail-open: if the hive fails, native sequential audit continues unaffected.
local _hive_audit_file="$ARTIFACTS_DIR/audit-hive-context.md"
local _hive_audit_context=""
if declare -f ruflo_execute_audit >/dev/null 2>&1 && \
   declare -f ruflo_available >/dev/null 2>&1 && \
   ruflo_available; then
    # Capture current code state for audit scope
    local _code_snapshot
    _code_snapshot=$(_safe_base_diff 2>/dev/null || true)
    if [[ -n "$_code_snapshot" ]] && ruflo_execute_audit "$_code_snapshot" "$_hive_audit_file"; then
        info "Ruflo parallel security audit hive complete — augmenting native audit"
        if [[ -s "$_hive_audit_file" ]]; then
            _hive_audit_context=$(head -c 3000 "$_hive_audit_file" 2>/dev/null || true)
        fi
    else
        warn "Ruflo parallel security audit failed — falling back to native sequential audit"
        emit_event "ruflo.audit_fallback" "reason=hive_failed" || true
    fi
fi

Then inject context into audit report (similar to review):

• Log findings from _hive_audit_context to audit_log
• Prefix with "## Parallel Security Audit Hive Findings" marker

Phase 3: Register Events in event-schema.json (After line ~356)

Add these entries in the event_types object:

"ruflo.audit_start": {
  "required": ["max_agents"],
  "optional": []
},
"ruflo.audit_complete": {
  "required": ["hive_id"],
  "optional": []
},
"ruflo.audit_failed": {
  "required": ["reason"],
  "optional": []
},
"ruflo.audit_fallback": {
  "required": ["reason"],
  "optional": []
}

Phase 4: Add Tests to sw-ruflo-adapter-test.sh

Add three test sections after existing review/CQ tests:

Test Section 1: Audit Hive Init Success

• Mock ruflo hive-mind init to return valid hive_id
• Call ruflo_execute_audit <diff> <artifact_file>
• Assert artifact file is created and non-empty
• Assert events emitted: ruflo.audit_start, ruflo.audit_complete

Test Section 2: Audit Hive Fallback on Failure

• Mock ruflo hive-mind init to fail (exit 1)
• Call ruflo_execute_audit
• Assert returns 1
• Assert event emitted: ruflo.audit_failed

Test Section 3: Audit Findings Stored to Pipeline Namespace

• Mock hive-mind operations
• Call ruflo_execute_audit
• Assert findings persisted to pipeline-<PIPELINE_ID> namespace via ruflo_store

---

Task Checklist

• Task 1: Add ruflo_execute_audit() function skeleton to ruflo-adapter.sh (lines ~900-950)
• Task 2: Implement hive initialization logic (lines ~950-1010)
• Task 3: Implement agent spawning for 4 specialists (lines ~1010-1030)
• Task 4: Implement diff storage and ADR context injection (lines ~1030-1060)
• Task 5: Implement prior review findings injection from pipeline-<PIPELINE_ID> namespace (lines ~1060-1080)
• Task 6: Implement orchestration call with audit-specific goal (lines ~1080-1110)
• Task 7: Implement findings aggregation via union + artifact write (lines ~1110-1140)
• Task 8: Implement hive shutdown and result persistence (lines ~1140-1160)
• Task 9: Update stage_audit() to call ruflo_execute_audit() before sequential checks (pipeline-stages-review.sh lines ~651-670)
• Task 10: Inject audit hive findings into audit_log in stage_audit() (pipeline-stages-review.sh lines ~665-700)
• Task 11: Register 4 new audit events in event-schema.json (config/event-schema.json after line 356)
• Task 12: Add test suite for ruflo_execute_audit() to sw-ruflo-adapter-test.sh (3 test sections, ~80 lines)
• Task 13: Run npm test and verify all existing tests pass
• Task 14: Manual verification: run a pipeline with audit stage enabled and confirm hive findings injected

---

Testing Approach

Test Pyramid:

• Unit tests (70%):

  • Audit hive init success/failure paths
  • Agent spawning with varying counts
  • Findings aggregation via union
  • Namespace isolation
  • Event emission correctness
  • Count: 8 unit tests in sw-ruflo-adapter-test.sh

• Integration tests (20%):

  • Audit stage calling ruflo_execute_audit() with fallback
  • ADR context injected into audit hive
  • Prior review findings read from pipeline-<PIPELINE_ID> namespace
  • Audit findings persisted to pipeline-<PIPELINE_ID> namespace
  • Count: 3 integration tests (in test suite + manual pipeline run)

• E2E tests (10%):

  • Full pipeline with audit stage enabled
  • Verify _hive_audit_context is injected into sequential audit checks
  • Verify emit_event "ruflo.audit_fallback" when hive fails
  • Count: 1 E2E validation (manual)

Critical Paths:

• ✓ Happy path: Hive init → spawn 4 agents → orchestrate → aggregate → return 0
• ✓ Error case 1: Hive init fails → return 1 → emit ruflo.audit_failed
• ✓ Error case 2: Ruflo unavailable → skip hive, native audit runs
• ✓ Edge case 1: Partial agent spawn failure → proceed with fewer agents
• ✓ Edge case 2: ADR context missing → skip injection, continue
• ✓ Edge case 3: Prior review findings missing → skip injection, continue

---

Definition of Done

✓ All acceptance criteria met:

• ruflo_execute_audit() added to ruflo-adapter.sh with fail-open pattern
• Four specialist agents configured: cve_scanner, secrets_detector, owasp_auditor, compliance_checker
• ADR context injected from adrs-<repo_hash> namespace
• Prior review findings read from pipeline-<PIPELINE_ID> namespace
• Audit findings stored to hive-audit-<PIPELINE_ID> namespace
• Results persisted to pipeline-<PIPELINE_ID> for downstream stages
• stage_audit() calls ruflo_execute_audit() with fail-open fallback
• Four events registered in event-schema.json: ruflo.audit_start, ruflo.audit_complete, ruflo.audit_failed, ruflo.audit_fallback
• Tests added to sw-ruflo-adapter-test.sh covering: hive success, hive failure, namespace isolation
• All existing tests pass: npm test
• No secrets/credentials in any new code
• Code follows project conventions (Bash 3.2 compatible, set -euo pipefail, event logging via emit_event)

---

Risk Assessment

Risk	Mitigation
Ruflo unavailable blocks pipeline	Fail-open design: ruflo_available check prevents any calls; native sequential audit fallback always succeeds
Hive spawn timeout stalls pipeline	ruflo_with_timeout 60 with circuit-breaker; timeout disables ruflo but doesn't block
ADR context missing breaks audit	Optional injection: _ns_hash=$(_ruflo_resolve_repo_hash) returns 1 if no hash, audit continues
Prior review findings namespace empty	Optional consumption: ruflo_recall returns empty string, audit continues without context
Memory storage failure	Non-blocking: `
Cross-repo namespace leaks	Mitigated: ADR namespace only populated when repo hash is determinable; gated by _ns_hash=$(_ruflo_resolve_repo_hash)
Hive findings conflict with sequential checks	By design: union aggregation means sequential checks see all findings (additive, not exclusive)

---

Why This Design Works

1. Replicates proven pattern: Identical to ruflo_execute_review() and ruflo_execute_compound_quality() — reduces bugs and maintenance burden
2. Minimizes blast radius: New function only, fail-open fallback to existing sequential checks
3. Clear specialist roles: Four agents (CVE, secrets, OWASP, compliance) have non-overlapping domains → less conflict, faster execution
4. Proper aggregation: Union (not consensus) because audit findings are additive — one agent's "CVE found" doesn't contradict another's "secrets found"
5. ADR context injection: Compliance checker can verify changes against architectural decisions (already indexed by design stage)
6. Prior review context: Audit stage can build on review findings without duplication
7. Pipeline isolation: Each pipeline run gets unique namespace (pipeline-<PIPELINE_ID>) — no cross-run contamination

---

Ready to implement. Shall I proceed with Phase 1?