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 bytests/test_adr_enforcement.pyfor 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 | Dynamic plugin skill loading — install at boot, discipline in the prompt, filtered per phase | Accepted |
| 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) | Accepted |
| 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) |
Accepted |
| 0050 | Auto-Agent HITL Pre-Flight Loop | Accepted |
| 0051 | Iterative production-readiness review | Accepted |
| 0052 | Sandbox-tier scenario testing | Accepted |
| 0053 | Ubiquitous Language as a Living Artifact | Accepted |
| 0054 | Term Auto-Proposer Loop (Dark-Factory Glossary Growth) | Accepted |
| 0055 | OpenTelemetry Instrumentation as the Telemetry Layer | Accepted |
| 0056 | ADR touchpoint enforcement — synchronous gate → asynchronous caretaker loop | Accepted |
| 0057 | Term-Pruner Loop (Dark-Factory Glossary Hygiene) | Accepted |
| 0058 | Edge-Proposer Loop (Dark-Factory Graph Densification) | Accepted |
| 0059 | Advisor Pattern — Self-Repairing Review | Proposed |
| 0060 | Atlas Graph View and Provenance | Proposed |
| 0061 | Atlas Entries as Evidence | Proposed |
| 0062 | Entry-Evidence Loop | Accepted |
| 0063 | Factory-Phase Drift Mitigation | Proposed |
| 0064 | Earlier Adversarial Pipeline | Proposed |
| 0065 | Remove CodeGroomingLoop | Accepted |
| 0066 | AgentPort: Dependency-Injection Boundary for Agent Runner | Proposed |
| 0067 | IssueFetcherPort: GitHub Issue Fetching Boundary | Proposed |
| 0068 | BotPRPort: Minimal Interface for Caretaker Bot-PRs | Proposed |
| 0069 | WorkspaceGCLoop: Autonomous Worktree Garbage Collection | Proposed |
| 0070 | ReviewInsightStorePort: Persistence Boundary for Review Feedback Patterns | Proposed |
| 0071 | RouteBackCounterPort: Testable Counter for Precondition Route-Backs | Proposed |
| 0072 | StaleIssueLoop: Auto-Close Stale General Issues | Proposed |
| 0073 | RunsGCLoop: Artifact Retention Enforcement | Proposed |
| 0074 | RetrospectiveLoop: Durable-Queue Pattern Analysis | Proposed |
| 0075 | MergeStateWatcherLoop: Autonomous Conflict Detection and Rebase | Proposed |
| 0076 | GitHubCacheLoop: Centralized GitHub Data Cache | Proposed |
| 0077 | PRUnstickerLoop: Goal-Driven HITL PR Resolution | Proposed |
| 0078 | PricingRefreshLoop: Autonomous LLM Pricing Drift Detection | Proposed |
| 0079 | ADRReviewerLoop: Autonomous Council Review for Proposed ADRs | Proposed |
| 0080 | EpicMonitorLoop: Autonomous Stale-Epic Detection and Progress Refresh | Proposed |
| 0081 | EpicSweeperLoop: Autonomous Completion-Based Epic Auto-Close | Proposed |
| 0082 | Declarative Gate Contract for Branch Protection | Proposed |
| 0083 | No ignored automated test gates | Accepted |
| 0084 | Auto-Agent as a Universal, Persistent, Root-Cause HITL Gate | Proposed |
| 0085 | Secrets never persist in the canonical audit stream | Accepted |
| 0086 | LiveCorpusReplayLoop: Shadow-Corpus Drift Detection | Proposed |
| 0087 | Prompt structure standard (XML tags, 8-criterion rubric, mechanical scoring) | Proposed |
| 0088 | LabelDriftWatcherLoop — Cross-Entity State-Machine Drift Caretaker | Accepted |
| 0089 | MemoryBacklogLoop — promote session-memory feedback to the find queue | Accepted |
| 0090 | Atlas — Knowledge Graph Dashboard Surface | Accepted |
| 0091 | Fold Epic Completion Sweep into Epic Monitor | Accepted |
| 0092 | Untrusted-text trust boundary for agent prompts | 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.