mrcharles
92956a9ae4
Founder ruling 2026-09-02: physical server-room access 100% human required — logged, approved, signed off. Branch protection lands immediately after this commit. Also excludes .gitea/ from the doc-pointer scan (framework dir, not docs). 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.
|
|
|
|
## PR process (founder ruling 2026-09-02) — physical access is 100% human-gated
|
|
|
|
- `main` is BRANCH-PROTECTED: no direct pushes, by anyone. All changes
|
|
land via PR with the sign-off template (`.gitea/pull_request_template.md`).
|
|
- **Two human approvals required to merge.** Gitea enforces the count.
|
|
Agents may author and push PR branches and implement review feedback —
|
|
agents NEVER approve, NEVER merge, NEVER bypass (`--no-verify` is not
|
|
a bypass for the approval count).
|
|
- Access-control changes (badge roster, unlock policy, door-adjacent
|
|
code) additionally require the template's checklist and a
|
|
founder-approved ticket.
|
|
- Full audit chain per change: Redmine ticket → PR description → two
|
|
named human approvals → merge → deployment note (#356).
|
|
|
|
## 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).
|