docs: bring the specification in line with the accepted implementation

The operator ruled the implementation repo's main (50c8719) the latest
and accepted state. Sync the spec to it.

Accepted changes are reflected: one bare-metal environment, TrueNAS bulk
storage, R2 off-cluster backup, CloudNativePG, single-node VPN gateway
with Cilium fail-closed, inbound WireGuard, per-app auth sidecars,
Renovate, the CI gate as approver, and the pm-agent. New ADR-0017..0025;
ADR-0016 corrected and accepted; R-* IDs unchanged, eight amended.

Where the implementation has simply not met a requirement, the
requirement stands and the shortfall is recorded in docs/16-known-gaps.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jakman85andClaude Opus 5.5 committed 2026-11-08 22:46:00 -06:00
1 parent 1ddc14b918
commit 250fb54154
43 files changed
+1672 -575

No files matched your search

+40 -34
View File
@@ -11,18 +11,18 @@ fully before making any change. These rules **override** any conflicting default
> requirement-tagged conformance test — never "merged," never a manual demo (R-TEST-01..05).
> See §7 and [`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md).
## 1. This repository defines intent, not implementation (yet)
## 1. This repository defines intent; the implementation has its own repository
Today this repo contains **specifications only**. Implementation artifacts (Helm values, Flux
Kustomizations, KubeVirt manifests, OpenTofu/Ansible IaC, etc.) will be added under an
`implementation/` tree **only after** the corresponding spec and ADRs are approved. Until then:
This repo contains **specifications only**. Implementation artifacts (Helm values, Flux
Kustomizations, KubeVirt manifests, Ansible IaC, the merge gate, the conformance tests) live in the
[implementation repo](https://gitea.home.keithjackson.dev/Home-Network/home-network-k3s-impl), whose
`CLAUDE.md` governs how work lands there.
- Do **not** invent implementation details that contradict the specs or ADRs.
- Do **not** create the `implementation/` tree until the roadmap phase that authorizes it is active
(see [`roadmap/phases.md`](roadmap/phases.md)).
- Do **not** add implementation artifacts to this repo.
- When you implement, the spec is the acceptance criteria. If the spec is wrong, blocking,
ambiguous, or missing, **you may not fix it yourself** — stop and escalate to the human operator/
architect (§2, §11). You may draft a proposal; you may not merge a spec change.
System Architect (§2, §11). You may draft a proposal; you may not merge a spec change.
## 2. The source-of-truth hierarchy
@@ -32,9 +32,9 @@ When two documents conflict, the higher item wins:
2. Approved ADRs in [`decisions/`](decisions/) — locked technology & pattern choices
3. Domain specs in [`docs/`](docs/)
4. [`roadmap/`](roadmap/) and [`agents/`](agents/) — sequencing and coordination
5. Implementation code (once it exists)
5. Implementation code
If you find a conflict, **stop and escalate it to the human operator/architect** — do not silently
If you find a conflict, **stop and escalate it to the human operator/System Architect** — do not silently
pick one interpretation, and do not resolve it by editing the specs yourself (you may not change
them, §11). Wait for the human to amend the spec, then implement against the amended spec.
@@ -44,7 +44,7 @@ Every major choice (k3s, Cilium, Longhorn, KubeVirt, Flux, SOPS, cert-manager, e
an ADR with rationale and rejected alternatives. If new information genuinely invalidates a
decision:
1. **Draft** a proposed superseding ADR and **escalate to the human operator/architect** — you may
1. **Draft** a proposed superseding ADR and **escalate to the human operator/System Architect** — you may
not merge it yourself (ADRs are specifications; §11 forbids agents changing them).
2. State what changed and why.
3. Only the human approves/accepts it. Implement against the new decision only after it is accepted.
@@ -55,7 +55,6 @@ Never edit an accepted ADR's decision in place. ADRs are an append-only, **human
- Every requirement has a stable ID like `R-NET-01`.
- Every ADR lists the requirement IDs it serves.
- Every task-board item lists the requirement IDs it satisfies.
- Every implementation PR references the requirement IDs and the spec sections it fulfills.
If you cannot trace a piece of work to a requirement, either it is out of scope or a requirement is
@@ -70,19 +69,20 @@ missing — surface it, don't proceed silently.
- Secrets live in git **encrypted** (SOPS + age). Never commit plaintext secrets. Never print a
decrypted secret into logs, PR descriptions, or agent output.
## 6. Two environments, one configuration
## 6. One environment, one configuration
- Author configuration so dev/test and prod differ **only** by environment-scoped overrides
(replica counts, node selectors, storage sizes, WAN endpoints, DNS zones).
- Production is the one live environment ([ADR-0017](decisions/adr-0017-single-environment-bare-metal-production.md)).
- Author configuration as a shared base plus an environment-scoped overlay (replica counts, node
selectors, storage sizes, WAN endpoints, DNS zones), so any future environment needs overrides only.
- Never fork the base configuration per environment. Use overlays/variables.
- **Never build directly on production.** Prod hardware is a design target, not a development
surface, until the roadmap declares it ready.
- **Changes reach production only through the PR gate and Flux** (R-ENV-03). Production is not a
surface to experiment on by hand.
## 7. Acceptance gates — proven by automated, reproducible behavior tests (non-negotiable)
A change is not "done" until an **automated, reproducible, behavior-based test** (Given/When/Then,
tagged with the requirement IDs it verifies) **passes green in dev/test** and is committed alongside
the change. A manual demonstration, a screenshot, or "it reconciled" is **not** acceptance
tagged with the requirement IDs it verifies) **passes green** (offline for L0/L1, against the live
cluster for L2/L3) and is committed alongside the change. A manual demonstration, a screenshot, or "it reconciled" is **not** acceptance
(R-TEST-01..04). The approach — reproducibility rules, layers, tooling, and the conformance suite —
is specified in [`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md) and
[`decisions/adr-0010-conformance-testing.md`](decisions/adr-0010-conformance-testing.md).
@@ -105,8 +105,11 @@ See [`agents/definition-of-done.md`](agents/definition-of-done.md) for the full
## 8. Coordination
- Claim work on [`agents/task-board.md`](agents/task-board.md) before starting; respect declared
dependencies (`blocked-by`).
- Implementation work is taken up through issues on the implementation repo; each unit of work
records a dated handoff entry in that repo's `decisions/`.
- Requirement status is derived from the repository (`./conformance/run.sh --status` in the
implementation repo), not from a hand-maintained board. [`agents/task-board.md`](agents/task-board.md)
is a frozen historical seed; nobody edits it.
- Follow [`agents/coordination-protocol.md`](agents/coordination-protocol.md) for handoffs,
interface contracts, and conflict resolution between agents/workstreams.
- Prefer small, reviewable, single-responsibility changes. One workstream should not silently change
@@ -120,9 +123,9 @@ See [`agents/definition-of-done.md`](agents/definition-of-done.md) for the full
**Open Questions** heading rather than burying ambiguity in the body.
- Keep the [`GLOSSARY.md`](GLOSSARY.md) authoritative — if you introduce a term, define it there.
## 10. What "you do not write code" means for the architect vs. what agents do
## 10. What "you do not write code" means for the System Architect vs. what agents do
The **architect** authored the specs, ADRs, and this coordination structure — no code. The
The **System Architect** authored the specs, ADRs, and this coordination structure — no code. The
**implementation agents** who consume this repo *do* write code (implementation *and* the automated
conformance tests that prove it), but only in service of an approved spec, only under the active
roadmap phase, and only against the automated acceptance gates above. Agents write tests; agents do
@@ -135,12 +138,14 @@ This is a hard boundary (R-TEST-06):
- **You MUST NOT modify** anything under [`docs/`](docs/), the requirements, accepted ADRs in
[`decisions/`](decisions/), the roadmap, or these coordination files. These are human-owned.
- **You MAY and MUST create/modify**: implementation code, **automated conformance tests**, the
implementation repo, and the *live coordination state* the specs explicitly delegate to you —
namely claiming/updating items on [`agents/task-board.md`](agents/task-board.md) and recording
proposals/escalations there. (The task board is a working surface; the *rules* around it are not.)
and the implementation repo, including its handoff log. Nothing in this repo is a working surface
for agents: any commit moves the spec `HEAD` away from the commit the implementation has pinned.
- **When the spec is wrong, blocking, ambiguous, or missing:** STOP. Do not proceed on a guess and
do not edit the spec. Raise an escalation on the task board (and draft a proposal if useful) for
the **human operator/architect** to decide. Resume only after the human amends the spec.
do not edit the spec. Raise an escalation as an issue on the implementation repo or directly to
the operator (and draft a proposal if useful) for the **human operator/System Architect** to
decide. Resume only after the human amends the spec.
- **Every spec advance is adopted explicitly** by the implementation
([`CONTRIBUTING.md`](CONTRIBUTING.md), "Adopting a spec change in the implementation").
- **Never** make the implementation pass by weakening the spec, the requirement, or the test's
intent. If reality can't meet the spec, that is an escalation, not a spec edit.
@@ -151,11 +156,12 @@ toward the target; they never move the target.
Full detail in [`CONTRIBUTING.md`](CONTRIBUTING.md). The rules that bind every change:
- **No work on `main`.** `main` holds only completed, reviewed work.
- **Every change is a feature branch** (`feature/…`, `fix/…`, `docs/…`, `chore/…`), **merged into
`main`** when complete (and, for implementation, when its conformance tests pass).
- **Local git for now; Gitea soon.** There is no remote host on this network yet — the prior
`home-network` Gitea is gone from this network. **Gitea is one of the first services brought online
on the cluster**, after which repos, the GitOps source, and CI/CD move to Gitea (Gitea Actions
running the Kyverno gate + Chainsaw conformance Job, with PRs as the enforced merge gate).
- **No work on `main`.** `main` holds only completed work.
- **Every change is a branch and a pull request.** A spec change is merged only by the human
operator. An implementation change merges on the green merge gate, the approver, with a non-author
review on sensitive paths ([ADR-0024](decisions/adr-0024-delivery-authority-ci-gate.md)).
- **Agents never push to `main`, never merge their own PR, and never post the administrator override
to clear their own work.**
- **Both repos are hosted on the platform's own Gitea**, which is also the GitOps source; Gitea
Actions runs the merge gate.
- **Never commit plaintext secrets** (SOPS-encrypted only, [`docs/07-security-and-secrets.md`](docs/07-security-and-secrets.md)).