Architecture Decision Records — Index¶
ADRs are operational decision history (per review #6, they live outside the architecture doc). The bible summarizes them; full text is here. Convention from ADR-0001: an agent's output is not governance until merged here via review.
| ADR | Title | Status | One-liner |
|---|---|---|---|
| 0001 | Establish the governance repository | Superseded (by ADR-0006) | One canonical, version-controlled home for governance; tmp/memory is scratch only. Historical, non-executable. |
| 0002 | Runtime baseline not measurable locally | Proposed | N = unmeasured (not zero); first work item is restoring measurability on Oracle. |
| 0003 | Name logical authorities, not paths | Accepted | Architecture names authorities; runtime resolves them; filesystems merely host them. |
| 0004 | Consume ContractPlane as a service | Proposed (decision required) | Read-only context is not policy-gated; source the gate as a service, not a local clone. |
| 0005 | Evaluator Pattern for Repository Governance | Accepted | Extract read-only, deterministic evidence collection from decision-making/mutation. |
| 0006 | Mac laptop purge and NAS-centric engineering layout | Proposed | Mac → stateless client; NAS → mirrors + sandbox; Oracle → execution; purge gated by RX-MIG receipts. |
| 0007 | Operational work System of Record (Beads + Dolt) | Candidate | Conclusion UNKNOWN until RX-BD-001 and RX-BD-002 pass; Git=config, Dolt=operational state. |
| 0008 | Read-only upstream authority location | Candidate — OPEN | Do not standardize directory name until ADR closes; graph-first projections preferred. |
| 0010 | Repository Convergence Operational Authority | Accepted | Assign operational authority for repository convergence to blu-cli under a five-command suite. |
| 0011 | Oracle Upstream Convergence — Remove Bluefly Runtime Ownership | Proposed | Converge Oracle to official gc/gt/beads/dolt; Bluefly contributes only IaC, packs, config; every deletion needs three-part upstream proof. |
| 0012 | Adopt OpenTofu for Infrastructure Provisioning | Accepted | Adopt OpenTofu as the reference provider for infrastructure provisioning (CAP-IAC-001). |
| 0013 | Repository Reset State Machine | Proposed | Model Repository Reset as three orthogonal systems: scheduler DAG, state machine, and authority model. |
| 0014 | Deploy Gas City strictly as configuration (zero-slop IaC) | Proposed | Packs, pinned imports, explicit providers, v2 formulas; behavior authority stays upstream. |
| 0015 | Dissolve the Skills Repository into PackV2 Packs | Accepted (direction) | Smallest Stable Owner: skill content migrates into owning packs; duplicated platform machinery retires with upstream-equivalence + consumer-ledger proof. |
| 0016 | Next-Generation SSH-less Deployment Platform | Proposed | Desired State Model with immutable Release Bundles severs CI-to-runtime SSH ties; Oracle becomes destroy/reprovision-safe. |
| 0017 | Repository Capability Convergence Audit | Proposed | Per-repo/module RETIRE/CONTRIBUTE/EVALUATE/RETAIN audit; do not retire working software for a design document. |
| 0018 | Blu as a Reasoning Engine Over External Context Providers | Proposed | Blu queries GitLab Orbit (SDLC) + Gas City (runtime) as authoritative context providers; owns only reasoning, not a duplicated graph. |
| 0019 | Execution Context as a Governed Platform Resource | Proposed | Execution context (agent/authority/credentials/filesystem) becomes first-class, same tier as runtimes/repos/config; prevents cross-context continuity confusion. |
| 0020 | 1Password Connect + SDK and Keycloak as the Standing Secrets/Identity Target | Accepted | Oracle runtime uses Connect; CI off-host uses CI_JOB_TOKEN then Service Account; Vault/.op-env SUPERSEDED. |
| 0021 | RFP serving authority: registry.yaml vs LiteLLM routing | Candidate — OPEN | registry.yaml says rfp is dev-only; LiteLLM already serves rfp-default/rfp-fast via Claude in production. No record links them. |
| 0022 | Bluefly Runtime Architecture — Gas City as Foundation | Accepted | Gas City is a peer consumer of Gas City, not Bluefly's architectural parent; Bluefly and Gas City both consume the Gas City SDK. Renumbered 2026-08-05 from un-indexed adr-0001-bluefly-runtime-gas-city-foundation.md (collided with ADR-0001). |
| 0023 | Repository Authority Model | Accepted | Formal model distinguishing kinds of repository authority (NAS/GitLab/Oracle) to stop "canonical" being used ambiguously. Renumbered 2026-08-05 from un-indexed adr-0002-repository-authority-model.md (collided with ADR-0002). |
| 0024 | Portable Execution Contract for Bluefly Projects | Proposed | DDEV stays the environment authority; delete workstation-only glue, add a thin Dev Container workspace layer, and split the four credential planes (secret values / SSH identity / CI / runtime) instead of one universal credential pipe. |
| 0025 | Verification Surfaces and Unversioned Runtime State | Proposed | Names two defect classes that recurred seven and four times in one night: a check that cannot fail for the reason it is trusted to detect, and runtime state invisible to every merge request. Rule B.5 ("runtime wins over docs") withdrawn 2026-08-26; replaced by ADR-0027. |
| 0026 | Gas City is the Runtime; Gas City is Configuration | Accepted | Gas City is the sole orchestration runtime; the official Gas City pack is imported configuration. gt in runtime is an incomplete cutover, not the target. |
| 0027 | Upstream Documentation is the Governing Contract | Accepted | Current docs.gascity.com is primary for Gas City semantics. Six primitives; city.toml portable names / .gc/site.toml paths; one Dolt per city. Runtime measures conformance. |
| 0028 | Gas City Repository Model | Proposed | GitLab is canonical source; Oracle registered rig is one non-bare working clone; agents execute in ephemeral git worktrees. Bare repos are not the Gas City rig type. Source intent ≠ live registration. |
Status values¶
Proposed → Accepted → Superseded (by ADR-N). Every ADR carries Status + Date + Related.