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>

hooks/audit-before-git.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Hook: audit-before-git (PreToolUse, matcher: ^bash$)
+# Fires on any bash call containing "git commit" or "git push" and blocks it
+# unless the fast rule audit passes. This makes the git hooks redundant-safe:
+# even if hooks are bypassed or missing, the agent cannot commit/push a
+# rule-violating state.
+set -euo pipefail
+
+CMD="${CRUSH_TOOL_INPUT_COMMAND:-}"
+
+if ! printf '%s' "$CMD" | grep -qE 'git[[:space:]]+(commit|push)'; then
+    echo '{}'
+    exit 0
+fi
+
+# Emergency bypass.
+if printf '%s' "$CMD" | grep -q -- '--no-verify'; then
+    echo '{"context": "Skipping rule audit (--no-verify). Use this ONLY in genuine emergencies."}'
+    exit 0
+fi
+
+REPO_ROOT="${CRUSH_PROJECT_DIR:-$(pwd)}"
+
+if bash "$REPO_ROOT/scripts/check-rules.sh" --fast >/dev/null 2>&1; then
+    echo '{"context": "Rule audit passed."}'
+    exit 0
+fi
+
+# Re-run with output so the violation is visible, then block.
+bash "$REPO_ROOT/scripts/check-rules.sh" --fast >&2 || true
+echo "BLOCKED: rule audit failed. Fix the violations above before committing or pushing." >&2
+exit 2

hooks/block-todos.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Hook: block-todos (PreToolUse, matcher: ^todos$)
+# Bans the todos tool. WORKING.md is the ONLY task tracker in this project,
+# so the task list is version-controlled and visible in every commit.
+#
+# Why: the todos tool's state is invisible to humans reviewing git history.
+# WORKING.md is committed, diffable, and survives across sessions.
+echo "BLOCKED: The todos tool is banned in this project. Use WORKING.md for ALL task tracking — edit it, then commit." >&2
+exit 2

hooks/enforce-bash.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Hook: enforce-bash (PreToolUse, matcher: ^bash$)
+# Intercepts every bash tool call and blocks two classes of violation:
+#   1. Banned host-mutating / network commands (per AGENTS.md policy).
+#   2. Host-level language toolchains — they must run inside Docker so the
+#      host stays clean.
+set -euo pipefail
+
+CMD="${CRUSH_TOOL_INPUT_COMMAND:-}"
+
+# --- 1. Banned commands -----------------------------------------------------
+# Extend PROJECT_BANNED_COMMANDS (space-separated) via env to add project-specific bans.
+BANNED_COMMANDS="${PROJECT_BANNED_COMMANDS:-sudo su doas apt apt-get dnf emerge pacman yum zypper apk opkg curl wget ssh scp telnet nc firefox chrome safari httpie}"
+for bc in $BANNED_COMMANDS; do
+    if printf '%s' "$CMD" | grep -qE "(^|[[:space:]])${bc}([[:space:]]|$)"; then
+        echo "BLOCKED: AGENTS.md — '$bc' is a banned command. This project is Docker-only; do host work through containers or approved wrappers." >&2
+        exit 2
+    fi
+done
+
+# --- 2. Host-level language tools ------------------------------------------
+# python3/go/node/npm/cargo/etc. must appear inside a `docker run|exec|build`.
+if printf '%s' "$CMD" | grep -qE '(^|[[:space:]])(python3?|go test|go vet|gofmt|go run|node|npm|npx|yarn|pnpm|ruby|java|javac|rustc|cargo)([[:space:]]|$)'; then
+    if ! printf '%s' "$CMD" | grep -qE 'docker (run|exec|build)'; then
+        echo "BLOCKED: AGENTS.md — language tools must run inside Docker, not on the host. Use: scripts/docker-run.sh <pinned-image> <command>" >&2
+        exit 2
+    fi
+fi
+
+echo '{}'

hooks/enforce-rules.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Hook: enforce-rules (PreToolUse, matcher: ^(edit|write|multiedit)$)
+# Inspects the target file path of every edit/write/multiedit and:
+#   1. Blocks edits to banned file types in production paths.
+#   2. Injects a "did you write a failing test first?" reminder for source edits.
+#
+# Banned file types are configurable via PROJECT_BANNED_SUFFIXES (regex alternation)
+# and PROJECT_BANNED_ALLOW (regex of paths that are exempt, e.g. vendored code).
+set -euo pipefail
+
+PATH_PREFIX="${CRUSH_WORKING_DIR:-/work}"
+FILE_PATH="${CRUSH_TOOL_INPUT_FILE_PATH:-}"
+
+# Strip common prefixes to get a repo-relative path.
+REL_PATH="${FILE_PATH#"$PATH_PREFIX"/}"
+REL_PATH="${REL_PATH#/}"
+
+BANNED_SUFFIXES="${PROJECT_BANNED_SUFFIXES:-}"
+BANNED_ALLOW="${PROJECT_BANNED_ALLOW:-^$}"
+
+# --- 1. Banned file types ---------------------------------------------------
+if [ -n "$BANNED_SUFFIXES" ] && printf '%s' "$REL_PATH" | grep -qE "\.($BANNED_SUFFIXES)$"; then
+    if ! printf '%s' "$REL_PATH" | grep -qE "$BANNED_ALLOW"; then
+        echo "BLOCKED: AGENTS.md language policy — $REL_PATH is a banned file type in production. Allowed only under: $BANNED_ALLOW" >&2
+        exit 2
+    fi
+fi
+
+# --- 2. TDD reminder for source-file edits ----------------------------------
+# Toggle via PROJECT_SOURCE_SUFFIXES (regex). Default: none (opt-in).
+SOURCE_SUFFIXES="${PROJECT_SOURCE_SUFFIXES:-}"
+TEST_PATTERN="${PROJECT_TEST_PATTERN:-_test\.}"
+if [ -n "$SOURCE_SUFFIXES" ] && printf '%s' "$REL_PATH" | grep -qE "\.($SOURCE_SUFFIXES)$"; then
+    if ! printf '%s' "$REL_PATH" | grep -qE "$TEST_PATTERN"; then
+        cat <<'EOF'
+{"context": "You are editing a source file. TDD is mandatory: did you write a FAILING test first? If not, stop and write the test before editing this file."}
+EOF
+        exit 0
+    fi
+fi
+
+echo '{}'

hooks/exit-protocol.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# Hook: exit-protocol (PreToolUse, matcher: .*)  — catch-all.
+# Enforces the project's definition of "done": if WORKING.md has any unchecked
+# task, inject context ordering the agent to finish them before responding.
+# This prevents premature "Done" responses.
+set -euo pipefail
+
+# Required by the hook protocol: consume stdin.
+cat >/dev/null
+
+REPO_ROOT="${CRUSH_PROJECT_DIR:-$(pwd)}"
+WORKING_FILE="$REPO_ROOT/WORKING.md"
+
+if [ -f "$WORKING_FILE" ]; then
+    UNCHECKED="$(grep -cF -- '- [ ]' "$WORKING_FILE" || true)"
+    if [ "$UNCHECKED" -gt 0 ]; then
+        TASKS_JSON="$(grep -F -- '- [ ]' "$WORKING_FILE" \
+            | sed 's/\\/\\\\/g; s/"/\\"/g' \
+            | awk -v ORS='\\n' '{print}' | sed 's/\\n$//')"
+        printf '{"context": "STOP. WORKING.md has %s unfinished task(s). You cannot declare work done or respond to the user while these remain:\\n%s\\nFinish them now. Do not respond until all are checked. Then clear WORKING.md and commit."}\n' \
+            "$UNCHECKED" "$TASKS_JSON"
+        exit 0
+    fi
+fi
+
+echo '{}'