Skip to content

Architecture Decision Records

Lightweight ADRs documenting key design decisions in HydraFlow.

Format

Each ADR has: Status, Date, Enforced by, Context, Decision, Consequences, and optionally Alternatives considered and Related links.

When referencing source code anywhere in an ADR (Related, Context, Decision, Consequences), use module:function_or_class format (e.g. src/config.py:HydraFlowConfig). Omit line numbers — they drift as code evolves and become stale quickly.

Enforced by

Every ADR with Status: Accepted MUST declare how it's enforced. Value is one of:

  • Test references — comma-separated paths to test files/functions that would fail if the decision were violated (e.g. tests/test_worktree.py, tests/test_state_machine.py::test_labels_transition). Files named here must exist.
  • (process) — the ADR enforces a workflow/convention (e.g. branch protection, ADR authoring style) rather than code behaviour.
  • (historical) — the ADR codifies a past decision worth keeping but no longer directly testable.
  • (none) — placeholder for Accepted ADRs still awaiting an enforcement test. Flagged by tests/test_adr_enforcement.py for follow-up; should be replaced with real references over time.

tests/test_adr_enforcement.py validates this line exists on every Accepted ADR and that named test files actually exist.

Index

ADR Title Status
0001 Five Concurrent Async Loops Accepted
0002 GitHub Labels as the Pipeline State Machine Accepted
0003 Git Worktrees for Issue Isolation Accepted
0004 CLI-based Agent Runtime (Claude / Codex / Pi.dev) Accepted
0005 PR Recovery and Zero-Diff Branch Handling in Implement Phase Accepted
0006 RepoRuntime Isolation Architecture Superseded
0007 Dashboard API Architecture for Multi-Repo Scoping Accepted
0008 Multi-Repo Dashboard Architecture Accepted
0009 Multi-Repo Process-Per-Repo Model Accepted
0010 Worktree and Path Isolation Architecture Accepted
0011 Epic Release Creation Architecture Accepted
0012 Epic Merge Coordination Architecture Accepted
0013 Screenshot Capture Pipeline Architecture Superseded
0014 Session Counter Forward-Progression Semantics Accepted
0015 Protocol-Based Callback Injection Gate Pattern Proposed
0016 VisualValidation SKIPPED Override Semantics Accepted
0017 Auto-Decompose Triage Counter Exclusion Accepted
0018 Screenshot Capture Pipeline Architecture Accepted
0019 Background Task Delegation Abstraction Layer Accepted
0020 autoApproveRow Border Context Awareness Superseded
0021 Persistence Architecture and Data Layout Accepted
0022 Integration Test Architecture — Cross-Phase Pipeline Harness Accepted
0023 Require Instantiation Verification for Test-Local Classes Proposed
0024 Implementation Retry Recovery Architecture Accepted
0025 Symmetric Field Assertion Checklist for Shared Return Types Accepted
0027 Duplicate Class Definitions — Merge-Artifact Pattern Proposed
0028 Event-Driven Report Pipeline with Extractable Widget Accepted
0029 Caretaker Background Loop Pattern Accepted
0030 Dashboard Routes Domain Decomposition Accepted
0031 Product Track Architecture — Discover and Shape Phases Proposed
0032 Per-Repo Wiki Knowledge Base (Karpathy Pattern) Accepted
0033 Gate Triage Call on Config Toggle, Not Just HITL Fallback Superseded
0034 Auto-Triage Toggle Must Gate Routing, Not Just Stat Tracking Accepted
0035 Tests Must Match Toggle State They Assert Proposed
0036 CLI Architecture — argparse with Config Builder Pattern Proposed
0037 Supersession Regex Must Include All Verb Forms Accepted
0038 Multi-Repo Architecture Wiring Pattern Proposed
0039 Stats Counter Placement in Delegating Helpers Rejected
0040 ADR Reviewer Proposed-Only Filter and Validator Scope Rejected
0041 GitHub as Source of Truth, Local Cache as Sidecar Accepted
0042 Two-tier branch model with automated release-candidate promotion Accepted
0043 Prompt structure standard (XML tags, 8-criterion rubric, mechanical scoring) Proposed
0044 HydraFlow Principles — the audit contract for new and existing repos Proposed
0045 Trust Architecture Hardening — Lights-Off Trust Fleet (10 loops + 2 non-loop subsystems) Proposed
0046 Meta-observability with bounded recursion — one layer of meta, no more Proposed
0047 Fake-adapter contract testing via cassette record/replay Proposed
0048 Auto-revert on RC red (extends ADR-0042) Proposed
0049 Trust-loop kill-switch convention (enabled_cb only, no config-only) Proposed
0050 Auto-Agent HITL Pre-Flight Loop Accepted
0051 Iterative production-readiness review Accepted
0052 Sandbox-tier scenario testing Accepted

Adding a new ADR

Copy the template, increment the number, fill in the sections. Mark superseded ADRs by setting **Status:** Superseded and adding a Superseded by: ADR-XXXX entry in the Related section rather than deleting them.