# Agent Guidelines — KNEL/doorman

Physical access control: badge-reader listener + tooling. Modern successor
of the 2018 Perl doorman (`legacy/doorman.pl`, snapshot from
[KNEL/LegacyTechops](https://git.knownelement.com/KNEL/LegacyTechops)).

House rules layering: `~/.zcode/AGENTS.md` (global) < PFVCluster
`AGENTS.md` (workspace) < THIS FILE. The more specific file wins.

## Authority (NON-NEGOTIABLE)

- No work without an approved Redmine ticket. Active work: **#355**
  (code & testing, laptop/office), under umbrella **#345**; deployment is
  **#356**. NEVER close tickets without explicit human permission.
- Ticket gate: `echo '#NNN' > .crush/active-ticket` before any modifying
  work; clear when done.
- Propose, never implement out-of-scope findings — open a sub-ticket.
- Security/access changes (door hardware, unlock policy, whitelists) are
  POLICY decisions — the human decides; the agent implements.

## Access channels

- SSH only (sshd is the only approved remote path). The qemu guest-agent
  is NEVER an execution channel. `qm guest exec` is banned mechanically.
- All SSH to fleet hosts routes through the PFVCluster chokepoints:
  [tests/remote.sh](https://git.knownelement.com/KNEL/PFVCluster/src/branch/main/tests/remote.sh).
- DNS names only — never IP literals.

## Scope boundary: Home Assistant

The HA side (webhook receiver, whitelist, automations, alerts) is owned by
the parallel pfv-bms session/repo. This repo ships ONLY the reader-host
side + the webhook contract documented in README.md. Do not edit
KNEL/pfv-bms from here.

## Scope boundary: server-room door ONLY (founder ruling 2026-09-02)

Badge access work is fully contained to the server-room door. Do NOT
integrate, configure, or touch any other smart locks in the house —
not even "obvious" ones. Any such ask is a new ticket for the founder
to approve.

## Engineering

- TDD red/green for all code (`scripts/test.sh` is the local gate).
- shellcheck zero-warning (info included) via `bash tests/shellcheck.sh`.
- This daemon stays bash + coreutils ONLY — the reader Pi gets no package
  installs, no CPAN, no Python (ruling 2026-08-31).
- NEVER restart/kill both readers simultaneously: deploy to the dev reader
  host (ultix-field), verify, then prod (pfvsvrpi) — serial, health-gated.
- Every command touching a remote host gets `timeout` (30s/120s/300s).
- Commit+push as work lands; conventional format; `[#NNN]` in subjects.

## Docs

Discourse is the documentation SoR
([VP TechOps](https://community.turnsys.com/c/vp-techops)). Repo .md files
are pointers or operational docs that must live beside code (this README).