chore: scaffold M0 — repo structure, ADRs, dev environment, pre-merge checklist

2026-08-02 10:26:49 +02:00
commit 581191e93a
20 changed files with 781 additions and 0 deletions
@@ -0,0 +1,25 @@
+# ADR-003: Deployment strategy
+
+**Status:** Accepted
+**Date:** 2026-08-02
+
+## Context
+
+We need a way to get merged code running on real infrastructure. Options considered: a Gitea Actions CI/CD pipeline, a fully manual deploy process, or a dedicated deployment platform. The project owner already runs (or intends to run) **Coolify** in the homelab, and wants it as the long-term deployment mechanism: Coolify connects to Gitea via webhook, and automatically pulls, builds, and deploys on merge to the appropriate branch.
+
+Building a full CI pipeline (lint, test, build, deploy stages) now, before there is any application code to test, would be effort spent on tooling with nothing yet to validate — directly against the founding strategy's core principle of avoiding infinite runway to real value (Section 1.1).
+
+## Decision
+
+- **Gitea remains the Git source of truth.** All code, config, and IaC live there.
+- **Coolify handles build and deployment**, triggered by a webhook on merge to `main`.
+- **CI is intentionally deferred.** For M0 and M1, a **manual pre-merge checklist** (`docs/architecture/pre-merge-checklist.md`) substitutes for automated checks. This is a conscious tradeoff, not an oversight — revisit once there's a real test suite worth automating.
+- **No staging branch/environment yet.** Given the MVP is read-only (Section 1.5), the blast radius of a bad production deploy is low. Revisit at v0.5, when the Execution Guard starts allowing real write actions against homelab infrastructure (founding strategy, Section 7).
+- The repository is structured to be Coolify-ready from day one (separate `docker-compose.prod.yml`, `docs/deployment/`) even though the actual Coolify connection is not made in M0 — there's nothing deployable yet.
+
+## Consequences
+
+- Merges to `main` will, once Coolify is connected, deploy directly to production with no automated gate in between — raises the real stakes of the manual pre-merge checklist; it needs to be used honestly, not treated as a formality.
+- We save the time cost of building and maintaining a CI pipeline before there's anything meaningful to run through it.
+- We accept slower feedback on regressions until CI is eventually introduced (tracked as a backlog item once a real test suite exists — see roadmap).
+- The Coolify connection itself (webhook setup, environment variables) is deliberately out of scope for M0 — it becomes real at the end of M1, once `main` contains a working service worth deploying.