jakman85andClaude Opus 4.8
e8c555cfeb
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]>
85 lines
4.9 KiB
Markdown
85 lines
4.9 KiB
Markdown
# Definition of Done
|
|
|
|
A change is **done** only when an **automated, reproducible, behavior-based test** for each relevant
|
|
gate below **passes green in dev/test**, the test is committed with the change and tagged with the
|
|
requirement IDs it verifies, and the change is traced to those IDs. A manual demonstration, a
|
|
screenshot, or "it reconciles" is **not** done (R-TEST-01..04, [`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)).
|
|
|
|
> **Governance (R-TEST-06):** you may not change the specifications to reach done. If the spec can't
|
|
> be met, that is an **escalation to the human**, not a spec/requirement/test-intent edit. Weakening
|
|
> a test so it passes is a defect, not a completion.
|
|
|
|
## Universal checklist (every change)
|
|
- [ ] Traced to one or more requirement IDs (`R-*`) and the spec/ADR it implements.
|
|
- [ ] An **automated behavior test** (Given/When/Then) exists, is committed with the change, tagged
|
|
with its `R-*` IDs, and **passes**; it appears in the coverage report.
|
|
- [ ] The test is **reproducible**: single-command, hermetic (self-provisioning + self-cleaning),
|
|
deterministic, and yields identical results on re-run.
|
|
- [ ] Expressed as GitOps (in git, reconciled by Flux) — no click-ops except ADR-sanctioned bootstrap.
|
|
- [ ] No plaintext secrets anywhere; secrets are SOPS-encrypted (and no secret printed in output).
|
|
- [ ] Authored once with environment-scoped overrides (no per-env base fork).
|
|
- [ ] Observability wired (metrics/logs) and at least the relevant alert exists.
|
|
- [ ] No specification/ADR/requirement was modified to achieve this (R-TEST-06); any spec problem was
|
|
escalated, not edited.
|
|
- [ ] Result recorded on the task board / PR with a link to the passing test run.
|
|
|
|
## Requirement-class gates (apply those relevant to the change)
|
|
|
|
> Each checkbox below is the **intent of an automated behavior test** — implement it as a
|
|
> reproducible, requirement-tagged test (see the behavior catalog in
|
|
> [`../docs/14-testing-and-conformance.md`](../docs/14-testing-and-conformance.md)), not a manual
|
|
> check. Safety-critical gates (marked *fault-injection*) must break the system and assert
|
|
> fail-closed / no-data-loss (R-TEST-05).
|
|
|
|
### State & rebuild (R-STATE-*)
|
|
- [ ] Destroy the workload entirely and re-apply from git; **data survives**.
|
|
- [ ] Stateful data is on `longhorn` (replicated) or the `bulk` tier — never ephemeral/hostPath.
|
|
- [ ] DR-critical data restores from an **off-cluster** backup (drill for at least one service/phase).
|
|
|
|
### Network isolation & egress (R-NET-*)
|
|
- [ ] With no explicit allows, the workload can reach **only DNS** (default-deny proven via Hubble +
|
|
probe).
|
|
- [ ] Declared `dependencies` work; an **undeclared** destination is blocked (negative test).
|
|
- [ ] `egress: internet` leaves via the home/WAN IP; `egress: vpn` leaves via the **VPN IP**.
|
|
- [ ] **VPN kill-switch:** tunnel forced down ⇒ the `vpn` workload leaks nothing; `internet`
|
|
workloads unaffected.
|
|
- [ ] Changing `egress` class in git re-routes with no workload rewrite.
|
|
|
|
### TLS (R-TLS-*)
|
|
- [ ] Endpoint serves a **valid, non-self-signed, unexpired** cert (external check), including for
|
|
`internal` services.
|
|
- [ ] Renewal is automatic (observed or verified via cert-manager) with no manual step.
|
|
|
|
### DNS & ingress (R-DNS-*)
|
|
- [ ] `<service>.home.keithjackson.dev` record appears automatically and routes correctly.
|
|
- [ ] `internal` is unreachable publicly; `public` is reachable + TLS-valid.
|
|
- [ ] Internal clients resolve to the internal Gateway (no public hairpin).
|
|
|
|
### Automated updates (R-UPD-*)
|
|
- [ ] Advances to a newer **stable** version automatically on schedule with **no human/AI edit**.
|
|
- [ ] A deliberately bad update is health-gated: **auto-rollback** + alert.
|
|
- [ ] A **pinned** service does not advance.
|
|
|
|
### Observability & alerting (R-OBS-*)
|
|
- [ ] Metrics + logs flow; a meaningful alert **fires** in a fault test and is delivered by **email**.
|
|
- [ ] Dashboard renders and is linked from the C2 UI.
|
|
|
|
### VM/IaaS (R-PLAT-03)
|
|
- [ ] VM created/started/stopped/destroyed via `kubectl`/`virtctl` (same K8s surface).
|
|
- [ ] VM disk is Longhorn-backed; rebuild preserves data; default-deny + egress class apply; guest
|
|
auto-updates.
|
|
|
|
### Security & auditability (R-SEC-*)
|
|
- [ ] Least-privilege RBAC (no broad cluster rights for workloads).
|
|
- [ ] The auditability proofs (isolation / egress path / kill-switch / TLS / backup) are producible.
|
|
|
|
### Per-service onboarding (WS-APPS)
|
|
- [ ] The service is **fully wired from its ServiceDefinition alone** (compute/storage/policy/egress/
|
|
TLS/DNS/monitoring/update) — no manual steps beyond merge.
|
|
|
|
## Phase exit
|
|
A phase is done when the **full conformance suite for that phase's requirements passes green**
|
|
(R-TEST-03) and the exit criteria in [`../roadmap/phases.md`](../roadmap/phases.md) are recorded with
|
|
links to the passing runs. Prod (Phase 7) additionally requires a successful **automated** prod DR
|
|
drill.
|