From 9836e94e48320d0cd5a927acd05be2f52d7ed84b Mon Sep 17 00:00:00 2001
From: reachableceo <charles@turnsys.com>
Date: Mon, 10 Aug 2026 09:23:41 -0500
Subject: [PATCH] docs(rules): mandate Unix utilities for editing, codify host
 hygiene
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add three policy updates to AGENTS.md and BASELINE-PROMPT.md:

1. Prefer awk/sed/grep/cut/tr for file editing over built-in harness
   edit tools, which can be unreliable with whitespace and indentation.
2. Host hygiene is inviolable: only git, docker, and Unix utilities on
   the host. One-off tools get docker-pulled; broadly useful tools get
   a Redmine ticket for the human to install via package manager.
3. Never install language runtimes or non-base tools on the host.

💘 Generated with Crush

Assisted-by: Crush
---
 AGENTS.md          | 4 ++++
 BASELINE-PROMPT.md | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 8ca1f37..88b6653 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -131,6 +131,7 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
 
 - **Stop over-thinking.** Get to code and output faster. Explore with code; gather ground truth. Do not burn tokens reasoning about things a quick command answers.
 - **Ask questions early** via `questions-v(N).md`. Don't ruminate or self-debate at length.
+- **Prefer Unix utilities (awk, sed, grep, cut, tr, etc.) for file editing and text processing** over built-in edit tools when feasible. Harness edit tools can be unreliable with whitespace/indentation; Unix tools are deterministic and exact. Use them for surgical edits, bulk substitutions, and structured text extraction.
 - **Farm work out to deterministic tooling:** linters, LSPs, formatters, test runners. If an LSP is wired up, use it; otherwise pull a Docker image and lint inside it. Do not parse huge code blocks in context.
 - **Use sub-agents as subcontractors** (see BASELINE-PROMPT.md §12): scoped spec in, distilled deliverable out. Never read 10+ files sequentially; batch into 2-3 agent calls. Read the 3-4 files you'll edit yourself; delegate the rest.
 
@@ -141,6 +142,9 @@ docker run --rm --env-file ~/projects/KNEL-AIMiddleware/discourse-cli/.env \
 
 ## Conventions
 
+- **Host hygiene is inviolable.** The host runs only: `git`, `docker`, and standard Unix utilities (`awk`, `sed`, `grep`, `cut`, `tr`, `jq`, `find`, `xargs`, etc.). No language runtimes, no package-managed tools beyond the base OS.
+- **If a one-off utility would help on the host,** `docker pull` a pinned image and run it ephemerally. Do not install it on the host.
+- **If a tool would be broadly useful across projects,** create a Redmine ticket requesting the human add it via the system package manager. Do not install it yourself.
 - **Docker/Kubernetes for everything** — cluster of 1 or 100 is the same. Don't presume scale.
 - **All development work happens in containers** — custom, off-the-shelf, or a mix. `docker pull` freely without asking. Use `scripts/docker-run.sh <pinned-image>` for one-offs.
 - **Container naming: never use Docker's default.** Always name with a project prefix (e.g. `<project>-<service>`). Enforced by `check-rules.sh`.
diff --git a/BASELINE-PROMPT.md b/BASELINE-PROMPT.md
index 994bbfe..050ce4c 100644
--- a/BASELINE-PROMPT.md
+++ b/BASELINE-PROMPT.md
@@ -54,6 +54,9 @@
 - **All development work happens in containers** — custom, off-the-shelf, or a mix. `docker pull` freely without asking.
 - **Container naming: never use Docker's default.** Always name with a project prefix (e.g. `<project>-<service>`).
 - Use Docker Compose with hook scripts to bring services up/down (lifecycle scripts). See `~/projects` for established examples.
+- **Host hygiene is inviolable.** The host runs only `git`, `docker`, and standard Unix utilities (`awk`, `sed`, `grep`, `cut`, `tr`, `jq`, `find`, `xargs`, etc.). No language runtimes or package-managed tools beyond the base OS.
+  - **One-off utility needed?** `docker pull` a pinned image and run it ephemerally. Do not install on the host.
+  - **Broadly useful tool?** Create a Redmine ticket requesting the human add it via the system package manager. Do not install it yourself.
 
 ## 7. Infrastructure-as-Code testing
 
@@ -106,3 +109,4 @@ This is scoped, contract-style work with a clear handback — not staff augmenta
 
 - **Red/green TDD for all code.** Write the failing test first.
 - **Linters on all code, as early as possible.** Be token-efficient — let deterministic tools find the issues.
+- **Prefer Unix utilities (awk, sed, grep, cut, tr, etc.) for file editing and text processing** over built-in harness edit tools when feasible. Harness edit tools can be unreliable with whitespace/indentation; Unix tools are deterministic and exact.