mrcharles
3a9124b16d
Modern successor of the 2018 Perl doorman (snapshot in legacy/): bash+coreutils HID decoder, HA webhook dispatch, systemd unit. Offline decoder suite green (9 tests); shellcheck zero-warning. Umbrella #345. Work item: https://projects.knownelement.com/issues/355
52 lines
2.3 KiB
Markdown
52 lines
2.3 KiB
Markdown
# 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.
|
|
|
|
## 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).
|