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, not implementation (yet)

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:

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

## 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 (once it exists)

If you find a conflict, **stop and escalate it to the human operator/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/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 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
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. Two environments, 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).
- 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.

## 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
(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

- Claim work on [`agents/task-board.md`](agents/task-board.md) before starting; respect declared
  dependencies (`blocked-by`).
- 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 architect vs. what agents do

The **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
  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.)
- **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.
- **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, 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).
- **Never commit plaintext secrets** (SOPS-encrypted only, [`docs/07-security-and-secrets.md`](docs/07-security-and-secrets.md)).