Skip to content

Pipeline Design 325

Jump to bottom
ezigus edited this page Apr 11, 2026 · 1 revision

Now I have full context on the existing patterns. Let me write the ADR.

Design: feat(ruflo): integrate audit stage with ruflo hive-mind specialist security agents

Context

The Shipwright pipeline's stage_audit() (scripts/lib/pipeline-stages-review.sh:651) currently runs four sequential security checks — secrets scanning, file permissions, || true usage, and test coverage delta. Two sibling pipeline stages already use ruflo hive-mind parallelism: ruflo_execute_review() (line 734) spawns security/code_quality/test_gap/architecture agents, and ruflo_execute_compound_quality() (line 898) spawns negative_tester/dod_auditor/e2e_validator agents. Both follow an identical structural pattern: init hive → spawn specialists → store diff in shared memory → orchestrate → aggregate via union → shutdown → write artifact → persist result to pipeline namespace. The audit stage is the natural next candidate for the same treatment, with domain-specific security specialist agents.

Constraints:

  • Bash 3.2 compatible (no associative arrays, no ${var,,})
  • Fail-open: hive failure must never block the pipeline — sequential checks always run
  • Known anti-pattern from failures.json: RUFLO_AVAILABLE must not be set before binary check passes (the existing ruflo_available guard handles this correctly)
  • Pipeline namespace isolation via SHIPWRIGHT_PIPELINE_ID to prevent cross-run data leaks
  • All ruflo CLI calls must respect RUFLO_USE_NPX toggle for PATH vs npx invocation

Decision

Add ruflo_execute_audit() to scripts/lib/ruflo-adapter.sh as a structural clone of the review/CQ pattern, adapted for security audit domain:

Agent specialization:

Agent Role Memory Key
CVE scanner Scan dependencies for known CVEs audit-cve-findings
Secrets detector Detect hardcoded secrets/credentials audit-secrets-findings
OWASP auditor Check for OWASP Top 10 patterns audit-owasp-findings
Compliance checker Verify logging, error handling, ADR compliance audit-compliance-findings

Data flow:

  1. stage_audit() reads $ARTIFACTS_DIR/review-diff.patch (produced by prior review stage)
  2. Calls ruflo_execute_audit(diff_content, artifact_file) — guarded by declare -f + ruflo_available
  3. Function initializes hive with --topology hierarchical --max-agents $RUFLO_AUDIT_MAX_AGENTS
  4. Stores bounded diff (8KB cap) + ADR context (from adrs-<repo_hash>) + prior review findings (from pipeline-<PIPELINE_ID>) into hive-audit-<PIPELINE_ID> namespace
  5. Orchestrates with --mode "audit" and 300s timeout, 20 max turns
  6. Aggregates findings via union (no Byzantine consensus — security findings are additive, not conflicting)
  7. Writes findings to $ARTIFACTS_DIR/audit-hive-context.md
  8. Persists truncated result (2KB) to pipeline-<PIPELINE_ID> namespace as stage-audit-result
  9. On any failure, returns 1 → stage_audit() emits ruflo.audit_fallback and sequential checks proceed unaffected

Error handling:

  • Hive init timeout: 30s via ruflo_with_timeout — returns 1 on failure
  • Spawn failure: non-fatal (|| true) — orchestration proceeds with available agents
  • Orchestration timeout: 300s (matches review/CQ)
  • Memory write failure: non-fatal — warn logged, empty artifact = no-op for caller (-s check)
  • Hive shutdown: unconditional via _ruflo_hive_shutdown in all code paths

Difference from review pattern: No Q-learning agent route (hooks route) in Phase 1. The review stage uses hooks route to dynamically adjust agent count based on issue context; audit agents are fixed at 4 security specialists since the audit domain is narrower and doesn't benefit from dynamic selection. This can be added later if audit workloads vary.

Alternatives Considered

  1. Single Claude invocation for audit (no hive) — Pros: zero new code, no new failure modes / Cons: no parallelism, no specialist agent expertise, inconsistent with review/CQ stages that already use hive-mind. Rejected because the issue explicitly requests parity.

  2. Reuse ruflo_execute_review() with --mode "audit" — Pros: zero new function / Cons: review agents (security, code_quality, test_gap, architecture) are wrong specialists for CVE/secrets/OWASP/compliance; the orchestration goal and memory keys would collide with review findings in the same pipeline run; namespace hive-review-* would conflate review and audit data. Rejected to maintain clean domain separation.

  3. Purpose-built ruflo_execute_audit() (chosen) — Pros: domain-specific agents, isolated namespace, follows proven structural pattern, fail-open by default, ~150 LOC of well-understood code / Cons: structural duplication with review/CQ functions (~80% identical boilerplate). Accepted because the boilerplate is the stable, tested pattern and premature extraction would couple three independent hive lifecycles.

Implementation Plan

Files to create: None

Files to modify:

File Change Location
config/event-schema.json Add ruflo.audit_start, ruflo.audit_complete, ruflo.audit_failed event types After line 356 (after ruflo.cq_fallback)
scripts/lib/ruflo-adapter.sh Add ruflo_execute_audit() function (~150 lines) After line 1017 (end of ruflo_execute_compound_quality())
scripts/lib/pipeline-stages-review.sh Insert ruflo hive invocation block into stage_audit() Between line 668 (local issues=0) and line 670 (# ── Secret Scanning ──)
scripts/sw-ruflo-adapter-test.sh Add 3 test sections: hive success, unavailable fallback, init failure After existing compound_quality test block

Dependencies: None new. Uses existing ruflo_with_timeout, ruflo_store, ruflo_recall, _ruflo_resolve_repo_hash, _ruflo_hive_shutdown, ruflo_available, emit_event — all already defined in ruflo-adapter.sh.

Risk areas:

Risk Severity Mitigation
review-diff.patch missing when audit runs Low Guarded by cat ... 2>/dev/null || true + empty check before calling ruflo_execute_audit
Namespace collision across concurrent pipeline runs Low SHIPWRIGHT_PIPELINE_ID uniqueness (epoch+PID fallback) — same as review/CQ
300s orchestration timeout exceeded Medium ruflo_with_timeout kills process; _ruflo_hive_shutdown runs unconditionally; returns 1 → fallback
RUFLO_AVAILABLE=true set before binary exists High Existing ruflo_available function checks binary presence — known anti-pattern from failures.json is already prevented by current guard
Stage insertion breaks stage_audit() flow Medium Insertion point is between variable init and first check section — no variable dependencies crossed; existing sequential checks remain untouched

Validation Criteria

  • ruflo_execute_audit function exists: grep -n "^ruflo_execute_audit()" scripts/lib/ruflo-adapter.sh
  • Function follows review/CQ structural pattern: init → spawn → store → orchestrate → aggregate → shutdown → write → persist
  • Four specialist security agents named in comments: CVE scanner, secrets detector, OWASP auditor, compliance checker
  • ADR context injected from adrs-<repo_hash> namespace via _ruflo_resolve_repo_hash
  • Prior review findings consumed from pipeline-<PIPELINE_ID> namespace key stage-review-result
  • Results stored to hive-audit-<PIPELINE_ID> namespace; outcome persisted as stage-audit-result
  • stage_audit() calls ruflo_execute_audit guarded by declare -f + ruflo_available — fail-open
  • Events ruflo.audit_start, ruflo.audit_complete, ruflo.audit_failed registered in config/event-schema.json
  • RUFLO_AUDIT_MAX_AGENTS env knob respected (falls back to RUFLO_MAX_AGENTS, then default 4)
  • Tests pass: bash scripts/sw-ruflo-adapter-test.sh (3 new sections: happy path, unavailable, init failure)
  • Existing tests unbroken: npm test
  • No Bash 3.2 incompatibilities (no associative arrays, no ${var,,})

Clone this wiki locally