From 799d2702612631f6c040f580b7ab8d1e206f831b Mon Sep 17 00:00:00 2001 From: reachableceo Date: Tue, 28 Jul 2026 18:49:39 -0500 Subject: [PATCH] docs: fix gardening variance + strengthen protocol for new directories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two variances from the gardening protocol were found during self-audit: the k8s/ and powerman/ directories were added but the root README.md directory table and the AGENTS.md Key Scripts table were not updated. Root cause: the gardening protocol enumerated STATUS.md and docmap.md but did not explicitly call out the root README.md directory table or the AGENTS.md Key Scripts table, so they were easy to miss when adding a new top-level directory. Fixes: - README.md: add k8s/ and powerman/ to the Directory Structure table - AGENTS.md: add install-cp.sh and powerman/setup.sh to Key Scripts Permanent fix (encode in protocol so it cannot recur): - Add rule 5 to the Automatic Gardening Protocol: when a new top-level directory is created, ALL directory listings must be updated (README.md table, AGENTS.md layout block, AGENTS.md Key Scripts) - Add rule 6: a grep-based self-audit command to run before commit, verifying the new directory appears in all four canonical files 💘 Generated with Crush Assisted-by: Crush:glm-5.2 --- AGENTS.md | 13 +++++++++++++ README.md | 2 ++ 2 files changed, 15 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 55732ff..04ea4bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,6 +59,17 @@ vendor/ Vendored KNELShellFramework 4. **Verify new docs are linked** — every new `.md` file must appear in [`docs/docmap.md`](docs/docmap.md) and be linked from at least one other doc. +5. **If a new top-level directory was created, update ALL directory listings:** + - [`README.md`](README.md) → "Directory Structure" table + - [`AGENTS.md`](AGENTS.md) → "Repository Layout" code block + - [`AGENTS.md`](AGENTS.md) → "Key Scripts" table (if the directory has + an entrypoint script) + Missing any one of these is a protocol violation. +6. **Self-audit before commit.** Before committing, run: + ``` + grep -lE 'new_dir_name' README.md AGENTS.md docs/docmap.md STATUS.md + ``` + Every new top-level directory must appear in all four files. ## Key Scripts @@ -68,6 +79,8 @@ vendor/ Vendored KNELShellFramework | [`tests/vm-validation.sh`](tests/vm-validation.sh) | Deploy + validate on sandbox VM | | [`tests/run-tests.sh`](tests/run-tests.sh) | Test suite | | [`dns-cluster-setup/setup.sh`](dns-cluster-setup/setup.sh) | DNS cluster replication | +| [`k8s/install-cp.sh`](k8s/install-cp.sh) | Bootstrap k3s HA control plane | +| [`powerman/setup.sh`](powerman/setup.sh) | Configure Cyclades PDU via powerman | | [`perf/deploy-tuning.sh`](perf/deploy-tuning.sh) | Deploy perf tunings | ## Key Docs diff --git a/README.md b/README.md index 77975a7..33fcc16 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,8 @@ Unified infrastructure repo for the Known Element Enterprises Proxmox R&D cluste | [`provisioning/`](provisioning/) | Server provisioning (SetupNewSystem.sh, security hardening, 2FA, NTP/DNS config, SNMP, Dell OMSA) | | [`tests/`](tests/) | Test suite + VM validation harness | | [`dns-cluster-setup/`](dns-cluster-setup/) | Technitium DNS cluster replication scripts | +| [`k8s/`](k8s/) | k3s cluster setup scripts (3-node HA control plane over Tailscale) | +| [`powerman/`](powerman/) | Cyclades PM10i PDU management via powerman on pfv-tsys1 | | [`perf/`](perf/) | Proxmox performance tuning, fleet audit, iperf, switch diagnostics | | [`netinfra/`](netinfra/) | pfv-netinfra-01/02 DNS/NTP setup + audit scripts | | [`switches/`](switches/) | Switch configuration captures |