Files

T

mrcharles 92956a9ae4 docs(governance): PR template + two-approver human gate for access work [#345 ]

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

2026-09-02 21:27:16 -05:00

3.3 KiB

Raw Blame History

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

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.
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). Repo .md files are pointers or operational docs that must live beside code (this README).

3.3 KiB Raw Blame History