Initial baseline: home platform (k3s + Longhorn) specification repository

Greenfield spec set for a GitOps-driven PaaS+IaaS home platform: vision & requirements (R-* IDs), architecture, 14 domain specs, 11 ADRs, roadmap (phases + workstreams), and AI-agent coordination (roles, protocol, definition-of-done, task board). Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-08-15 22:37:56 -05:00
commit e8c555cfeb
@@ -0,0 +1,55 @@
+# Architecture Decision Records (ADRs)
+
+ADRs are an **append-only ledger** of the significant technology and pattern choices for this
+platform. Each records the context, the decision, the rejected alternatives, and the requirements it
+serves. **Do not edit an accepted decision in place** — supersede it with a new ADR.
+
+> **ADRs are specifications and are immutable to AI agents** (R-TEST-06). Agents may *draft* a
+> proposed ADR and escalate it, but only the **human operator/architect** approves/accepts or edits
+> ADRs. See [`../AGENTS.md` §3 and §11](../AGENTS.md).
+
+## Process (read before proposing a change)
+
+1. To change a decision, create a **new** ADR with the next number and set `Status: Proposed`,
+   `Supersedes: ADR-XXXX`. (Agents draft + escalate; the human approves.)
+2. State what new information invalidates the old decision.
+3. On approval, set the new ADR `Accepted` and the old one `Superseded by: ADR-YYYY`.
+4. Never silently re-interpret an accepted ADR (see [`../AGENTS.md` §3](../AGENTS.md)).
+
+## Template
+
+```markdown
+# ADR-XXXX — <title>
+- Status: Proposed | Accepted | Superseded by ADR-YYYY
+- Date: <YYYY-MM-DD>
+- Serves: <requirement IDs, e.g. R-NET-01, R-NET-06>
+- Supersedes: <ADR-ZZZZ or —>
+
+## Context
+<forces, constraints, why a decision is needed>
+
+## Decision
+<what we chose, stated decisively>
+
+## Alternatives considered
+<options and why rejected>
+
+## Consequences
+<positive, negative, follow-ups, risks>
+```
+
+## Index
+
+| ADR | Title | Status | Serves |
+|---|---|---|---|
+| [0001](adr-0001-kubernetes-distribution-k3s.md) | Kubernetes distribution: k3s | Accepted | R-PLAT-01 |
+| [0002](adr-0002-cni-cilium.md) | CNI & network policy & ingress: Cilium + Gateway API | Accepted | R-NET-01..07, R-DNS-01 |
+| [0003](adr-0003-storage-longhorn.md) | Distributed storage: Longhorn (+ bulk tier, Velero) | Accepted | R-STATE-01..04 |
+| [0004](adr-0004-gitops-flux.md) | GitOps engine: Flux CD | Accepted | R-GITOPS-01..03 |
+| [0005](adr-0005-vm-workloads-kubevirt.md) | VM workloads: KubeVirt + CDI | Accepted | R-PLAT-03 |
+| [0006](adr-0006-tls-cert-manager-letsencrypt.md) | TLS: cert-manager + Let's Encrypt (DNS-01) | Accepted | R-TLS-01..03 |
+| [0007](adr-0007-secrets-sops-age.md) | Secrets: SOPS + age | Accepted | R-SEC-01 |
+| [0008](adr-0008-vpn-egress-model.md) | VPN egress model: Gluetun sidecar + Cilium Egress Gateway | Accepted | R-NET-05/06 |
+| [0009](adr-0009-automated-image-updates.md) | Automated updates: Flux image automation + Renovate | Accepted | R-UPD-01..03 |
+| [0010](adr-0010-conformance-testing.md) | Conformance testing: automated, reproducible, behavior-based | Accepted | R-TEST-01..06 |
+| [0011](adr-0011-test-tooling-kyverno-chainsaw.md) | Conformance test tooling: Kyverno + Chainsaw | Accepted | R-TEST-01..05 |