mrcharles
37d27f1158
Founder ruling 2026-09-02: no gates for code/host work; two-human approval applies to the badge-ID control file (separate private repo). https://projects.knownelement.com/issues/345
73 lines
3.3 KiB
Markdown
73 lines
3.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.
|
|
|
|
## Gate scope (founder ruling 2026-09-02, revised same day)
|
|
|
|
- **This repo (code) is fast-moving**: tests + shellcheck are the only
|
|
gates; commit+push per standing policy. The two-approval requirement
|
|
on `main` was removed by founder ruling — "no gates" for code/host
|
|
work on pfvsvrpi and ultix-field.
|
|
- **The human gate lives on the badge-ID control file**:
|
|
[KNEL/access-roster](https://git.knownelement.com/KNEL/access-roster)
|
|
(private, PR-only, two human approvals enforced). The listener NEVER
|
|
carries badge data — a change to who can open the door means a PR
|
|
there, never a change here.
|
|
- Deployment discipline still applies: ultix-field (dev) first, verify,
|
|
then pfvsvrpi (prod) — serial, health-gated.
|
|
|
|
## 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).
|