home-network-k3s/agents/definition-of-done.md

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).

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), 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 are recorded with links to the passing runs. Prod (Phase 7) additionally requires a successful automated prod DR drill.