feat: bootstrap meta — cross-project best-practices template

Extract patterns from 18 projects across two machines (12 local infra +
6 remote personal/business via ssh survey). Ship a reusable Gitea template
with AGENTS.md, 5 Crush PreToolUse hooks, git pre-commit/pre-push, a
generalized rules engine, shared bash library, Makefile, lifecycle scripts,
and gardening loop. Includes the canonical BASELINE-PROMPT.md (13 sections)
and PATTERNS.md (standardization scorecard).

The repo self-applies: it passes its own shellcheck (zero info-level),
make fast, and all check-rules.sh checks.

💘 Generated with Crush

Assisted-by: Crush via Crush <crush@charm.land>

PATTERNS.md

@@ -0,0 +1,247 @@
+# Cross-Project Pattern Extraction
+
+**Scope:** 18 projects surveyed across two machines:
+- **Local (`ultix-streaming`):** 12 infra/stack projects — `dotfiles`, `EngineeringWorkstation`, `EngStack`, `football`, `hermes-rceo-streaming`, `KNEL-AIMiddleware`, `KNELIAC`, `netbird`, `PFVCluster`, `TSYSDevStack-SupportStack-Cloudron`, `WorkstationStack`, `TSYSDevStack-SupportStack-LocalWorkstation`.
+- **Remote (`ultix-offstage`):** 6 personal/business projects — `CharlesNWybleResume`, `rceo-automation-espanso-private`, `RCEO-PersonalAssistant`, `ReachableCEO-Profile-FullTimeEmployment`, `RevGen-TimeForMoney`, `ThreeYearPlan`.
+
+This document records the patterns that recur, the inconsistencies between them,
+and the decisions the repo makes to drive inconsistency to zero.
+
+---
+
+## 1. AGENTS.md — recurring structure
+
+A canonical section set emerges from the 12 files that have one (8 local + 4 remote):
+
+| Section | Prevalence |
+|---|---|
+| Git commit & push policy | 12/12 |
+| Project overview / context | 11/12 |
+| Key commands / build cheat sheet | 10/12 |
+| Repository layout (ASCII tree) | 9/12 |
+| Status / journal maintenance | 9/12 |
+| Conventions & naming | 8/12 |
+| DO / DON'T | 7/12 |
+| Validation / testing | 7/12 |
+| Key files reference | 6/12 |
+| Quick start / onboarding | 5/12 |
+
+**Decision:** the template's `AGENTS.md` ships all ten sections in a fixed order,
+so every project has the same skeleton. Filler is bracketed for replacement.
+
+---
+
+## 2. Shared cross-project preferences (the house style)
+
+These recur strongly and are baked into the template:
+
+1. **Auto-commit + push is mandatory and non-negotiable.** Stated with ALL-CAPS force in nearly every file. The template states the override-once and lets the hooks enforce it.
+2. **Atomic commits — one logical change per commit.** Universal.
+3. **Conventional-commit format** (`feat:`/`fix:`/`docs:`/…). Universal, but the **💘 Crush attribution footer is inconsistent**: mandated only by `football` and `KNELIAC`; absent on the remote entirely. **Decision:** the template mandates the footer once, in the AGENTS.md commit block.
+4. **Docker-only host hygiene.** The single most consistent convention across *both* machines (`KNEL-AIMiddleware`, `EngStack`, `LocalWorkstation`, `RCEO-PersonalAssistant`, `ThreeYearPlan`, `CharlesNWybleResume`). **Decision:** enforced by hook (`hooks/enforce-bash.sh`) and rule, and supported by `scripts/docker-run.sh`.
+5. **Sub-agents encouraged.** Explicit in `football`, `ThreeYearPlan`, `RCEO-PersonalAssistant`. **Decision:** standard section in the template.
+6. **No secrets in git (infra genre).** Inverted on the remote private repos (`RCEO-PersonalAssistant` deliberately commits credentials). **Decision:** the template keeps the infra stance (`.env` gitignored) as the default; private repos may opt out.
+
+**Inconsistencies the template resolves:**
+- `shellcheck` is mandated by `PFVCluster` and `football` but unmentioned elsewhere → the template mandates it for all shell, via Docker.
+- "Keep the host clean" is phrased four different ways → one canonical phrasing.
+- Auto-commit override language varies in strength → stated once, authoritatively.
+
+---
+
+## 3. Git hooks — the biggest gap, now standardized
+
+**Finding:** custom git hooks are essentially unused. Only **3 of 18** projects have any:
+
+| Project | Hook | Mechanism | Installer |
+|---|---|---|---|
+| `football` | `pre-commit` (4-check SDLC gate: shellcheck, unit tests, coverage, doc-sync) | `core.hooksPath githooks/` | `scripts/setup-githooks.sh` |
+| `KNEL-AIMiddleware` | `pre-push` (block on dirty tree) | `core.hooksPath .githooks/` | **none** (manual `git config`) |
+| `RCEO-PersonalAssistant` | `pre-commit` (fast audit) + `pre-push` (full Docker tests) | **copy** into `.git/hooks/` | `scripts/setup-hooks.sh` |
+
+Three different install mechanisms; one project has no installer at all.
+
+**Decision:** the template uses the **copy** approach (most portable: works on any clone, no config mutation, idempotent) with a single `scripts/setup-hooks.sh`, and combines both policy philosophies:
+- `pre-commit` = fast audit with a **hot-path bypass** for `STATUS.md` / `JOURNAL.md` / `WORKING.md` (so frequent status commits stay frictionless) — proven in RCEO.
+- `pre-push` = full audit (incl. `make test`) — proven in RCEO — plus the dirty-tree gate — proven in KNEL-AIMiddleware.
+
+---
+
+## 4. Crush hooks — an entirely untapped capability (except one project)
+
+**Finding:** Crush `hooks` are used by **exactly one project** — `RCEO-PersonalAssistant`. Every other `crush.json` (and most projects have none) defines only `lsp`/`mcp`/`options`, never `hooks`. All process enforcement elsewhere is prose in AGENTS.md — manually enforced, violable.
+
+RCEO's crush.json wires five `PreToolUse` hooks that form a behavioral guardrail layer complementing the git hooks:
+
+| Hook | Matcher | Effect |
+|---|---|---|
+| `block-todos.sh` | `^todos$` | bans the todos tool; WORKING.md is the only tracker |
+| `enforce-bash.sh` | `^bash$` | blocks banned commands + host language toolchains |
+| `enforce-rules.sh` | `^(edit\|write\|multiedit)$` | blocks banned file types; TDD reminder on source edits |
+| `audit-before-git.sh` | `^bash$` | runs the fast audit before any `git commit`/`git push` |
+| `exit-protocol.sh` | `.*` | blocks stopping while WORKING.md has unchecked tasks |
+
+**Decision:** the template generalizes all five into `hooks/`, configurable via env vars (`PROJECT_BANNED_COMMANDS`, `PROJECT_BANNED_SUFFIXES`, `PROJECT_SOURCE_SUFFIXES`, …) so they are project-agnostic. This is the template's highest-leverage feature: it converts the one-off RCEO invention into a reusable baseline.
+
+---
+
+## 5. The rules engine — `check-rules.sh`
+
+RCO's `check-rules.sh` is the best reusable artifact found. Its core abstractions:
+
+- A `check()` accumulator classifying each rule as **pass / warn / fail**, with `FAIL > 0 ⇒ exit 1` and `WARN` non-fatal.
+- A `--fast` mode (used by pre-commit) that silences per-check output and skips slow checks.
+- Self-checking categories: shellcheck, Docker image pinning (no `:latest`), required-files manifest, doc freshness (STATUS.md/JOURNAL.md touched today), git state, hooks-installed, WORKING.md completion, unresolved `CNW:` markers.
+
+**Decision:** the template's `check-rules.sh` generalizes this — language-specific checks (Go test coverage, gofmt) are dropped or made opt-in via `PROJECT_*` env; universal checks (shellcheck, image pinning, required files, doc freshness, hygiene, WORKING.md, CNW markers, merge-conflict markers) are kept. The `check()` accumulator and `--fast`/`--quiet` flags move into `scripts/lib/common.sh` so any script can reuse them.
+
+---
+
+## 6. Scripts — driving the shebang/boilerplate chaos to zero
+
+**Findings:**
+- **Three incompatible shebang variants** across projects: `#!/usr/bin/env bash` (best), `#!/bin/bash`, `#!/usr/bin/bash` (non-portable).
+- **Four different `set`-flag policies**: `set -euo pipefail` (best), `set -e` only, `set -uo pipefail`, none. KNEL-AIMiddleware uses `set -e` only — piped failures silently swallowed; `BuildAll.sh`'s `docker compose … | tail` can report green on failure.
+- **The ANSI color block is copy-pasted into ~10 scripts.**
+- **`log_*` helpers are redefined per project** (and per-script in KNEL-AIMiddleware, where they aren't even functions).
+- **Repo-root resolution** is re-rolled in nearly every script.
+- **No shared cross-project library exists.** Only `EngStack` factors helpers (`scripts/lib.sh` build-time + `lib/common.sh` runtime).
+
+**Decision:** `scripts/lib/common.sh` provides the deduplicated primitives once: ANSI colors, `log_info/ok/warn/error/step`, `have()`, `die()`, `repo_root()`, `as_root()`, `docker_run()`, and the `init_counters`/`check`/`print_summary_and_exit` audit helpers. All template scripts use `#!/usr/bin/env bash` + `set -euo pipefail`.
+
+---
+
+## 7. Task runners — five conventions, standardized to one
+
+**Findings:** no `Makefile`/`Taskfile`/`justfile` exists anywhere. Five incompatible conventions for the same semantic verbs:
+
+| Project | Convention |
+|---|---|
+| football | `./run.sh <subcommand>` |
+| KNEL-AIMiddleware | `scripts/<Verb>.sh` |
+| EngStack | `scripts/<verb>-<noun>.sh` |
+| PFVCluster | `tests/<name>.sh` |
+| hermes-agent | npm workspace scripts |
+
+The recurring semantic targets — **build, test, lint, validate, status, clean, setup** — map cleanly onto one target set that doesn't exist.
+
+**Decision:** a single `Makefile` provides `setup`, `validate`, `fast`, `lint`, `test`, `status`, `clean`, `help`. It is pure dispatch to `scripts/`; projects override `test`/`clean` for their stack. CI, hooks, and humans now share one set of verbs.
+
+---
+
+## 8. CI — present in exactly one project
+
+Only `hermes-agent` has CI (22 GitHub Actions workflows — an exemplar: change-detection orchestrator, reusable-workflow lanes, SHA-pinned actions, supply-chain/OSV scans, live PR-comment bot). The other 17 have none.
+
+**Decision:** the template doesn't ship CI (it's stack-dependent), but `make validate` + `make lint` give any future workflow a uniform entry point. The hermes-agent `ci.yml` orchestrator is the documented growth path.
+
+---
+
+## 9. Crush configuration layers — documented but unused
+
+Crush defines a priority chain (`$HOME/.config/crush/crush.json` → `crush.json` → `.crush.json`). In practice:
+- The **global** config (`dotfiles`) is trivial (attribution style only) — no shared LSP/MCP baseline.
+- Only **2 projects** have a project-local `crush.json` (KNEL-AIMiddleware: 4 LSP + 36 MCP via wrappers; RCEO-PersonalAssistant: hooks only).
+- The highest-priority `.crush.json` layer is **unused anywhere**.
+- **No project sets `model` or `provider`** in config.
+
+**Decision:** the template ships only the `hooks` block in `crush.json` (the universally-applicable part). LSP/MCP remain project-local concerns. A future shared global config could baseline common LSPs (bash, markdown) and universal MCPs (context7) once.
+
+---
+
+## 10. Crush memory — a singleton, now a template
+
+Only `PFVCluster` has operational memory (`.crush/memory/operational.md`). Its format — Identity → Tracking Systems (with READY/PARTIAL/BLOCKED status) → Tooling → Access chokepoints → Key commands → Mandatory rules → Credential TODOs — is strong and reusable.
+
+**Decision:** the template ships `.crush/memory/operational.md` as a fill-in skeleton.
+
+---
+
+## 11. KNEL-AIMiddleware wrapper ecosystem — a standardization opportunity (not in the template)
+
+`KNEL-AIMiddleware` hand-maintains **38 near-identical** wrapper scripts (`mcp-*-wrapper.sh`, `lsp-*-wrapper.sh`) for its MCP/LSP fleet. ~90% of each file is duplicated boilerplate (container-cleanup stanza, `docker run -i --rm --name`, env passthrough). Drift is already visible (default style, double-passed creds, one structurally-different LSP wrapper). There is **no generator**; they were hand-cloned by an agent over many sessions.
+
+**Recommendation (out of scope for the template):** replace the 38 files with one parameterized launcher driven by a declarative `servers.yaml` manifest, plus a `gen-wrappers.sh`. The template's `docker-run.sh` + `lib/common.sh` show the direction; the same idea applies at fleet scale.
+
+---
+
+## 12. Workflow documents — WORKING.md / STATUS.md / JOURNAL.md
+
+The remote personal genre contributes a discipline absent from infra: a **task/state/document triad** enforced by hooks:
+
+- **WORKING.md** — the only task tracker (todos tool banned); commits blocked while `- [ ]` remain; cleared before responding.
+- **STATUS.md** — agent-maintained dashboard humans read; staleness is a warning.
+- **JOURNAL.md** — append-only ADR/pattern log; no today-entry is a warning.
+- **`CNW:` markers** — flag unresolved questions for the human; empty markers are a warning.
+
+**Decision:** all four are in the template, and check-rules.sh enforces their freshness/completion.
+
+---
+
+## Standardization scorecard
+
+| Inconsistency | Was | Now |
+|---|---|---|
+| Shebangs | 3 variants | `#!/usr/bin/env bash` |
+| `set` flags | 4 policies | `set -euo pipefail` |
+| Color/log boilerplate | copy-pasted ~10× | `lib/common.sh` |
+| Task runner | 5 conventions | one `Makefile` |
+| Git hook install | 3 mechanisms, 1 missing | one `setup-hooks.sh` (copy) |
+| Git hook coverage | 3/18 projects | every project, two hooks |
+| Crush hooks | 1/18 projects | every project, five hooks |
+| Rules engine | 1 project (Go-specific) | generalized, project-agnostic |
+| Crush memory | 1 project | skeleton in template |
+| AGENTS.md structure | bespoke per project | canonical 10-section skeleton |
+| 💘 commit footer | 2/18 projects | mandated in template |
+
+---
+
+## 13. Global baseline prompt integration
+
+After the initial extraction, the owner shared a draft "global baseline prompt"
+(an Apple Note of operating observations gathered over weeks of working with
+agents). It encodes principles that cut across every project and that the
+template now reflects. The cleaned canonical version lives in
+[`BASELINE-PROMPT.md`](BASELINE-PROMPT.md); the project-level specialization is
+in `AGENTS.md`. New artifacts and checks added:
+
+### New policy encoded
+
+| Principle (baseline §) | How the template enforces it |
+|---|---|
+| **Stop over-thinking; ask early** (§1, §9) | `questions-v1.md` skeleton + AGENTS.md "Questions" section; required-files check fails if absent |
+| **Token efficiency / farm to tooling** (§2) | `make lint` runs shellcheck in Docker; AGENTS.md "Working Style" forbids parsing huge code in context |
+| **Redmine = SoR for work; Discourse = SoR for docs** (§3) | AGENTS.md "Systems of Record" section; `make garden` flags oversized non-Discourse `.md` |
+| **Git .md = stubs to Discourse** (§3) | `scripts/garden.sh` reports oversized `.md` lacking a Discourse URL |
+| **`tea` CLI for PRs; off-workstation → PR** (§4) | AGENTS.md "Git Workflow" policy |
+| **Shift-left CI/CD, lockstep local + hosted** (§5) | AGENTS.md "CI/CD" section; `make fast` runs at pre-commit |
+| **Docker/k8s for everything; container naming** (§6) | new container-naming rule in `check-rules.sh` (every compose service needs `container_name`); `docker-compose.yml.example` + `scripts/up.sh` / `scripts/down.sh` |
+| **STATUS.md = scratchpad, not SoR; has Inbox** (§8) | STATUS.md reframed; Inbox section for mid-task interruptions ("don't pivot") |
+| **Questions file** (§9) | `questions-v1.md` artifact + required-files check |
+| **Belt-and-suspenders enforcement** (§10) | already present (git hooks + Crush hooks) — now documented as policy |
+| **Gardening loop** (§11) | `scripts/garden.sh` + `make garden` target |
+| **Sub-agents as subcontractors** (§12) | AGENTS.md "Working Style" |
+| **TDD + linters** (§13) | AGENTS.md "TDD & Linting"; `enforce-rules.sh` TDD reminder (opt-in via `PROJECT_SOURCE_SUFFIXES`) |
+
+### New template artifacts
+
+- `BASELINE-PROMPT.md` — the cleaned canonical global prompt (lives in the meta root; projects inherit).
+- `questions-v1.md` — git-tracked question log skeleton.
+- `docker-compose.yml.example` — lifecycle template with project-prefix naming.
+- `scripts/up.sh`, `scripts/down.sh` — compose lifecycle wrappers.
+- `scripts/garden.sh` — doc-sprawl / Discourse-migration report.
+
+### New `check-rules.sh` checks
+
+- **Container naming** (§6): every service in a `docker-compose*.y*ml` must declare `container_name:`; failure otherwise.
+- **Questions file required**: `questions-v1.md` must exist (required-files manifest).
+
+### New Makefile targets
+
+`make garden`, `make up`, `make down` — standard verbs across every project.
+
+### What stayed project-level (not globalized)
+
+- `sectestbed-` / `preprod-` VM testing semantics — IAC-workstream-specific; left as AGENTS.md prose, not a mechanical check.
+- Redmine Gantt / dependency modeling — workflow-specific.
+- Specific DNS/cloudron/SITER production details — out of scope.