Pipeline Design inline

Architecture Decision Record Complete ✅

I've created docs/ADR-AUDIT-STAGE-HIVE.md — a comprehensive Architecture Decision Record for the audit stage hive-mind integration.

What the ADR Covers

1. Component Decomposition (5 Components)

• stage_audit() — Pipeline orchestrator
• ruflo_execute_audit() — Hive executor with timeout/circuit breaker
• 4 Specialist agents — CVE, secrets, OWASP, compliance (parallel workers)
• Shared hive memory — Context bridge between agents
• Error handling — Fail-open design with native fallback

2. Interface Contracts

• Function signatures with exit code contract (0|1)
• Finding schema (severity, category, remediation)
• Event schema (audit_start, complete, failed, fallback)
• Memory namespace structure for context injection

3. Security Analysis (STRIDE)

• Spoofing ✅ — Role enforcement at hive spawn
• Tampering ✅ — EXIT trap + atomic writes
• Repudiation ✅ — Event logging for all operations
• Information Disclosure ✅ — 8KB diff bound + git-ignore
• Denial of Service ✅ — 300s timeout + circuit breaker
• Elevation of Privilege ✅ — Agents sandboxed, no hardcoded secrets

4. Design Decisions & Alternatives

• ✅ Chosen: Hive-mind parallel specialists (parallel execution + specialist capability)
• ❌ Rejected: Sequential native checks (too slow)
• ❌ Rejected: External SaaS (incompatible with self-hosted)
• ❌ Rejected: Separate processes (harder coordination)

5. Trade-Offs & Consequences

• Speed vs. Capability — Accept 3x latency for specialist analysis
• Reliability vs. Completeness — Fail-open + native fallback
• Diff Size vs. Memory Safety — 8KB truncation prevents exhaustion
• Throughput vs. Latency — 4 agents optimal for init/execution balance

6. Data Flow & Component Diagram

• ASCII architecture showing hive init → spawn → orchestrate → aggregate → shutdown
• Data flow from diff input through parallel processing to findings output
• Exit paths for both success and failure modes

7. Testing Strategy

• Unit tests (96 passing — already done)
• Integration tests (Task 1)
• Performance benchmarks (Task 2, <90s target)
• Security validation (Task 3, no secrets)
• Resilience testing (Tasks 4-7, timeout/spawn/truncation/context)

8. Configuration & Failure Modes

• Environment variables and .shipwright/defaults.json
• Complete failure mode table with recovery procedures
• Circuit breaker strategy and SIGTERM handling

---

How to Use This ADR

For Code Review:

• Reference sections on interface contracts (what inputs/outputs are valid)
• Check security properties (STRIDE mitigations)
• Verify error handling matches documented failure modes

For Maintenance:

• Update "Approval History" when reviewed
• Add revision entries when design changes
• Reference specific ADR sections in commit messages

For Future Design Work:

• Component diagram shows interaction boundaries
• Data flow shows where context enters/exits
• Alternatives section explains past decisions (prevents repeating rejected approaches)

---

Next Actions

This ADR is ready for:

1. ✅ Review by team lead and security team
2. ✅ Reference in validation tasks (Tests 1-8)
3. ✅ Merge with feature PR once validation completes
4. ✅ Update with approval signature + final date

The ADR supports the 8 validation tasks outlined in the validation plan—specifically:

• Tests 1-4 verify the core architecture works
• Tests 5-7 validate edge cases and resilience
• Test 8 (finalization) updates this ADR with approval signatures

All three planning documents are now in place and ready for execution.