home-network-k3s/AGENTS.md

# AGENTS.md — Rules of Engagement

This file governs how AI agents (and their human reviewers) work inside this repository. Read it
fully before making any change. These rules **override** any conflicting default behavior.

> **Two governing constraints, above all others:**
> 1. **You may not change the specifications.** The `docs/` tree, the requirements, and accepted
>    ADRs are human-owned and immutable to agents (R-TEST-06). You implement against them and prove
>    conformance; you never edit them to fit your implementation. See §2 and §11.
> 2. **Conformance is proven only by automated, reproducible behavior tests.** "Done" means a green,
>    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; the implementation has its own repository

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** 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/
  System Architect (§2, §11). You may draft a proposal; you may not merge a spec change.

## 2. The source-of-truth hierarchy

When two documents conflict, the higher item wins:

1. [`docs/00-vision-and-scope.md`](docs/00-vision-and-scope.md) — requirements (`R-*` IDs)
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

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.

## 3. Do not re-litigate decisions

Every major choice (k3s, Cilium, Longhorn, KubeVirt, Flux, SOPS, cert-manager, etc.) is captured in
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/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.

Never edit an accepted ADR's decision in place. ADRs are an append-only, **human-approved** ledger.

## 4. Requirement traceability is mandatory

- Every requirement has a stable ID like `R-NET-01`.
- Every ADR lists the requirement IDs it serves.
- 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
missing — surface it, don't proceed silently.

## 5. GitOps-first, click-ops-never

- The desired state of the cluster lives in git and is reconciled automatically.
- Manual changes to the running cluster are prohibited **except** where an ADR explicitly carves out
  an exception (e.g. a bootstrap step, an out-of-band edge-router config). Such exceptions must be
  documented and, where possible, later folded back into IaC.
- Secrets live in git **encrypted** (SOPS + age). Never commit plaintext secrets. Never print a
  decrypted secret into logs, PR descriptions, or agent output.

## 6. One environment, one configuration

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

The behaviors each change must prove (each expressed as an automated test):

- **No data loss on rebuild** — destroy and recreate the workload; state survives (R-STATE-*).
- **Default-deny holds** — the workload cannot reach services it wasn't explicitly allowed to
  (R-NET-*).
- **Correct egress path** — internet-class services egress locally; VPN-class services egress only
  through the VPN, with a verified kill-switch (R-NET-*).
- **Trusted TLS** — the endpoint serves a valid, non-self-signed, auto-renewing certificate
  (R-TLS-*).
- **Observed** — metrics, logs, and at least one meaningful alert exist and fire correctly
  (R-OBS-*).
- **Hands-off updates** — the service advances to new stable versions automatically per policy,
  with no hand-authored change (R-UPD-*).

See [`agents/definition-of-done.md`](agents/definition-of-done.md) for the full checklist.

## 8. Coordination

- 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
  another workstream's interfaces — negotiate the contract change first.

## 9. Style & conventions

- Markdown for all specs. One concept per file. Link generously between documents.
- Use requirement IDs and ADR numbers in prose so references stay stable when files move.
- Be decisive in specs. Where a genuine open question remains, record it under an explicit
  **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 System Architect vs. what agents do

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
not write specs.

## 11. Specifications are immutable to agents (governance)

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

The point: the specification is the fixed target. Agents move the implementation and its tests
toward the target; they never move the target.

## 12. Version-control workflow

Full detail in [`CONTRIBUTING.md`](CONTRIBUTING.md). The rules that bind every change:

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