Architecture Decision Records¶
Lightweight ADRs documenting key design decisions in HydraFlow.
Format¶
Each ADR has: Status, Date, Enforcement, Enforced by (when required), Context, Decision, Consequences, and optionally Alternatives considered and Related links. A control-plane ADR also carries a lineage line (Precedent and/or Divergence — see below).
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.
Lineage — Precedent and Divergence (optional)¶
Two optional, single-line header fields (see ADR-0113) let a control-plane ADR — a decision that defines the control system — separate inherited engineering from genuine divergence:
**Precedent:** <tradition> (<canonical source>)— the named engineering tradition this decision inherits. Must be a real, citable tradition; retrofitted branding fails review.**Divergence:** <assumption>, <forcing condition>, <rule> (<receipt>)— the assumption in that tradition that breaks here, citing the receipt (an ADR, incident, or audit finding) that forced it. ADivergence:without a receipt is not accepted.
Write each as its own line (not a bullet); both the bold-inline and plain
forms parse. The working heuristic: unforced invention is a defect; forced
invention has a named forcing condition and a receipt. The P1.17 audit check
(advisory today, escalating to blocking once the seed pass lands) warns when a
control-plane ADR carries neither line and flags any receipt-less Divergence:.
Enforcement¶
Every ADR with Status: Accepted (outside a shrinking grandfather list)
MUST declare an **Enforcement:** kind — see ADR-0100.
Value is one of:
enforced— asserts a runnable invariant. Requires an**Enforced by:**line naming typed-prefix checks (pytest:tests/test_x.py,make:some-target) that must resolve (the file/function/target must exist) and be side-effect-free.manual— a real guardrail that is human-verified rather than machine-run. Requires an**Enforced by:**process pointer.decision-of-record— a choice with no runtime predicate to check (no**Enforced by:**required).
tests/test_adr_conformance_coverage.py is the CI-blocking coverage ratchet:
it validates every non-grandfathered Accepted ADR declares a recognized
**Enforcement:** value, that enforced checks resolve to a real
pytest node or Makefile target and aren't on the mutating-target denylist,
and that the grandfather list only shrinks. AdrConformanceLoop is the
post-merge companion that actually executes enforced checks on a slow
cadence and files remediation issues on drift.
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 | Superseded |
| 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 | Accepted |
| 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 | Accepted |
| 0024 | Implementation Retry Recovery Architecture | Accepted |
| 0025 | Symmetric Field Assertion Checklist for Shared Return Types | Accepted |
| 0027 | Duplicate Class Definitions — Merge-Artifact Pattern | Accepted |
| 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 | Superseded |
| 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 | Accepted |
| 0036 | CLI Architecture — argparse with Config Builder Pattern | Superseded |
| 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 | Accepted |
| 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 | Superseded |
| 0056 | ADR touchpoint enforcement — synchronous gate → asynchronous caretaker loop | Superseded |
| 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 | Accepted |
| 0061 | Atlas Entries as Evidence | Accepted |
| 0062 | Entry-Evidence Loop | Accepted |
| 0063 | Factory-Phase Drift Mitigation | Proposed |
| 0064 | Earlier Adversarial Pipeline | Accepted |
| 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 | Accepted |
| 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 Panel 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) | Accepted |
| 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 | Superseded |
| 0092 | Untrusted-text trust boundary for agent prompts | Accepted |
| 0093 | Loop fitness as a measured contract | Accepted |
| 0094 | Two-level convergence: Gate + ConvergenceLedger | Accepted |
| 0095 | Approve-path gating and live convergence (Phase 2a) | Accepted |
| 0096 | Boundary verdict recording (Phase 2b) | Accepted |
| 0097 | Attempt counter migration into the ledger (Phase 2c) | Accepted |
| 0098 | Convergence oscillation caretaker (Phase 2d) | Accepted |
| 0099 | Orchestration as a Control System | Accepted |
| 0100 | ADR conformance as a measured contract | Accepted |
| 0101 | Disturbance Dampener — feedforward ratchet + burn-down loop | Proposed |
| 0102 | Convergence gate general availability (flag removed) | Accepted |
| 0103 | Continuous Human-on-the-Loop Steering Channel | Accepted |
| 0104 | Auto-tightening ratchet | Accepted |
| 0105 | Autonomous Convergence via Decomposition | Proposed |
| 0106 | Thread-level event-loop freeze detector | Accepted |
| 0107 | Collapse Discover + Shape into Plan — Triage → Plan Directly | Accepted |
| 0108 | Deterministic-Simulation Fault Injection on the Sandbox Compose — Evaluation | Proposed |
| 0109 | Opt-in "ultra" deep-review tier for the review phase | Accepted |
| 0110 | Provider/Harness Backend Split — z.ai as a Claude-harness backend | Accepted |
| 0111 | In-framework flow (DAG) runtime for workers and phases | Accepted |
| 0112 | Per-Issue Isolation via Local Git Clone | Accepted |
| 0113 | ADR lineage — Precedent and Divergence lines | Accepted |
| 0114 | Optional per-type EventBus subscription | Accepted |
| 0115 | Auto-diagnose before human for audit + escape surfaces | Accepted |
| 0116 | Prompts as a measured contract | Accepted |
| 0117 | Observed prompt coverage — the denominator is measured, not inferred | Accepted |
| 0118 | Observability belongs to the SRE agent, not the loops | Accepted |
| 0119 | Credit failover — reroute work to GLM instead of pausing when Claude credits are exhausted | Accepted |
| 0120 | The stillness control architecture — setpoint regulators, an optimization layer, and innovation-filtered sensing | Proposed |
| 0121 | The repo charter (charter.yaml) + drift caretaker — conformance as data | Proposed |
| 0122 | Vocabulary scopes for the three assurance disciplines | Proposed |
| 0123 | Bidirectional enforcement — every rule declares which direction it binds | Proposed |
| 0124 | Tier-2 goal supervisor — a Fable "mini-me" over Tier-1's liveness signals | Proposed |
| 0125 | Mutation gauntlet — measuring gate sensitivity by injecting known faults | Proposed |
| 0126 | Golden-baseline finder calibration — measuring a generative finder's noise floor | Proposed |
| 0127 | Judge calibration — scoring a judge's verdicts against outcomes with proper scoring rules | Proposed |
| 0128 | External Claude security-review Action as an out-of-band assurance anchor | Proposed |
| 0129 | Checkable-assertion density as an ADR setpoint-erosion series | Proposed |
| 0130 | Prompt outcome pairing — make the form rubric ungameable before a floor | Proposed |
| 0131 | Spec intake gate — stress-testing prose before it becomes a setpoint | Proposed |
| 0132 | The cognitive-process constitution — the harness as a governor of thought | Proposed |
| 0133 | Vitals methodology — widened-limit multiplicity, published MDE, and time-between-events charts | Proposed |
| 0134 | Per-repo model/harness selection — run Claude and GLM projects side by side | Accepted |
| 0135 | Factory runs as a launchd service; operator Stop is a latch honoured by autostart and the liveness kernel | Accepted |
| 0136 | ADR drift enforcement is a deterministic cited-symbol CI gate, not a caretaker loop | Accepted |
| 0137 | Fenced IssueDriver and director runtime boundary | Accepted |
| 0138 | Gateway account identity and sanitized route visibility | Accepted |
| 0139 | Shadow routing policy resolver and hash-linked decision record | Accepted |
| 0140 | Revision-safe policy workspace and the operator write boundary | Accepted |
| 0141 | Bounded, reversible routing enforcement — the resolve-and-mint canary | Accepted |
| 0142 | Multi-account pools and bounded fallback | Accepted |
| 0143 | PAAA — Purpose, Articles, Actors, Artifacts — and the declare / decide / act seam | Accepted |
| 0144 | Trace-grounded retrospective findings — anchors, not advice | Proposed |
| 0145 | Charter-declared loops — the repo owns the workflow, the factory owns governance | Proposed |
| 0146 | SRE v1 — the exception sensor | Accepted |
Adding a new ADR¶
Increment the number and copy an existing ADR's metadata block (e.g. ADR-0002 for a single check, or ADR-0049 / ADR-0053 for multiple), then fill in the sections. There is no separate template file.
Every Accepted ADR MUST declare an **Enforcement:** line — see the
Enforcement section above for the three kinds and what each
requires. The coverage ratchet blocks a new Accepted ADR that omits or
mis-declares it. When you choose enforced, get the **Enforced by:**
SHAPE right (this is the common footgun):
- Each check is TYPED: it starts with
pytest:(e.g.pytest:tests/test_foo.pyorpytest:tests/test_foo.py::test_bar) ormake:(a non-mutating target). A bare or backtick-wrapped path parses as prose and fails the ratchet. - ONE check goes inline on the marker:
**Enforced by:** pytest:tests/test_foo.py. - For MULTIPLE checks, put the marker on its own line and list one check per plain continuation line:
**Enforced by:**
pytest:tests/test_a.py
pytest:tests/test_b.py
- Never repeat the
**Enforced by:**marker (only the first is parsed, so the rest are silently dropped); never comma-join checks on one line.
Mark superseded ADRs by setting **Status:** Superseded and adding a Superseded by: ADR-XXXX entry in the Related section rather than deleting them.