phase0: add architecture guardrails, CI gates, per-language AGENTS.md
Non-negotiable structural rules that apply to every Claude Code session in
this repo and to every commit, enforced via three defense-in-depth layers:
1. PreToolUse hook in .claude/settings.json blocks any Write/Edit that
would push a file past the 500-line hard cap. Auto-loads for any
Claude session in this repo regardless of who launched it.
2. scripts/githooks/pre-commit (installed via scripts/install-hooks.sh)
enforces the LOC cap, freezes migrations/ unless [migration-approved],
and protects guardrail files unless [guardrail-change] is present.
3. .gitea/workflows/ci.yaml gets loc-budget + guardrail-integrity jobs,
plus mypy --strict on new Python packages, tsc --noEmit on Node
services, and a syft+grype SBOM scan.
Per-language conventions are documented in AGENTS.python.md / AGENTS.go.md /
AGENTS.typescript.md at the repo root — layering (router->service->repo for
Python, hexagonal for Go, colocation for Next.js), tooling baseline, and
explicit "what you may NOT do" lists.
Adds scripts/check-loc.sh (soft 300 / hard 500, reports 205 hard and 161
soft violations in the current codebase) plus .claude/rules/loc-exceptions.txt
(initially empty — the list is designed to shrink over time).
Per-service READMEs for all 10 services + PHASE1_RUNBOOK.md for the
backend-compliance refactor. Skeleton packages (compliance/{domain,
repositories,schemas}) are the landing zone for the clean-arch rewrite that
begins in Phase 1.
CLAUDE.md is prepended with the six non-negotiable rules.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sharang Parnerkar
123
scripts/check-loc.sh
Executable file
123
scripts/check-loc.sh
Executable file
@@ -0,0 +1,123 @@
|
||||
#!/usr/bin/env bash
|
||||
# check-loc.sh — File-size budget enforcer for breakpilot-compliance.
|
||||
#
|
||||
# Soft target: 300 LOC. Hard cap: 500 LOC.
|
||||
#
|
||||
# Usage:
|
||||
# scripts/check-loc.sh # scan whole repo, respect exceptions
|
||||
# scripts/check-loc.sh --changed # only files changed vs origin/main
|
||||
# scripts/check-loc.sh path/to/file.py # check specific files
|
||||
# scripts/check-loc.sh --json # machine-readable output
|
||||
#
|
||||
# Exit codes:
|
||||
# 0 — clean (no hard violations)
|
||||
# 1 — at least one file exceeds the hard cap (500)
|
||||
# 2 — invalid invocation
|
||||
#
|
||||
# Behavior:
|
||||
# - Skips test files, generated files, vendor dirs, node_modules, .git, dist, build,
|
||||
# .next, __pycache__, migrations, and anything matching .claude/rules/loc-exceptions.txt.
|
||||
# - Counts non-blank, non-comment-only lines is NOT done — we count raw lines so the
|
||||
# rule is unambiguous. If you want to game it with blank lines, you're missing the point.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
SOFT=300
|
||||
HARD=500
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
EXCEPTIONS_FILE="$REPO_ROOT/.claude/rules/loc-exceptions.txt"
|
||||
|
||||
CHANGED_ONLY=0
|
||||
JSON=0
|
||||
TARGETS=()
|
||||
|
||||
for arg in "$@"; do
|
||||
case "$arg" in
|
||||
--changed) CHANGED_ONLY=1 ;;
|
||||
--json) JSON=1 ;;
|
||||
-h|--help)
|
||||
sed -n '2,18p' "$0"; exit 0 ;;
|
||||
-*) echo "unknown flag: $arg" >&2; exit 2 ;;
|
||||
*) TARGETS+=("$arg") ;;
|
||||
esac
|
||||
done
|
||||
|
||||
# Patterns excluded from the budget regardless of path.
|
||||
is_excluded() {
|
||||
local f="$1"
|
||||
case "$f" in
|
||||
*/node_modules/*|*/.next/*|*/.git/*|*/dist/*|*/build/*|*/__pycache__/*|*/vendor/*) return 0 ;;
|
||||
*/migrations/*|*/alembic/versions/*) return 0 ;;
|
||||
*_test.go|*.test.ts|*.test.tsx|*.spec.ts|*.spec.tsx) return 0 ;;
|
||||
*/tests/*|*/test/*) return 0 ;;
|
||||
*.md|*.json|*.yaml|*.yml|*.lock|*.sum|*.mod|*.toml|*.cfg|*.ini) return 0 ;;
|
||||
*.svg|*.png|*.jpg|*.jpeg|*.gif|*.ico|*.pdf|*.woff|*.woff2|*.ttf) return 0 ;;
|
||||
*.generated.*|*.gen.*|*_pb.go|*_pb2.py|*.pb.go) return 0 ;;
|
||||
esac
|
||||
return 1
|
||||
}
|
||||
|
||||
is_in_exceptions() {
|
||||
[[ -f "$EXCEPTIONS_FILE" ]] || return 1
|
||||
local rel="${1#$REPO_ROOT/}"
|
||||
grep -Fxq "$rel" "$EXCEPTIONS_FILE"
|
||||
}
|
||||
|
||||
collect_targets() {
|
||||
if (( ${#TARGETS[@]} > 0 )); then
|
||||
printf '%s\n' "${TARGETS[@]}"
|
||||
elif (( CHANGED_ONLY )); then
|
||||
git -C "$REPO_ROOT" diff --name-only --diff-filter=AM origin/main...HEAD 2>/dev/null \
|
||||
|| git -C "$REPO_ROOT" diff --name-only --diff-filter=AM HEAD
|
||||
else
|
||||
git -C "$REPO_ROOT" ls-files
|
||||
fi
|
||||
}
|
||||
|
||||
violations_hard=()
|
||||
violations_soft=()
|
||||
|
||||
while IFS= read -r f; do
|
||||
[[ -z "$f" ]] && continue
|
||||
abs="$f"
|
||||
[[ "$abs" != /* ]] && abs="$REPO_ROOT/$f"
|
||||
[[ -f "$abs" ]] || continue
|
||||
is_excluded "$abs" && continue
|
||||
is_in_exceptions "$abs" && continue
|
||||
loc=$(wc -l < "$abs" | tr -d ' ')
|
||||
if (( loc > HARD )); then
|
||||
violations_hard+=("$loc $f")
|
||||
elif (( loc > SOFT )); then
|
||||
violations_soft+=("$loc $f")
|
||||
fi
|
||||
done < <(collect_targets)
|
||||
|
||||
if (( JSON )); then
|
||||
printf '{"hard":['
|
||||
first=1; for v in "${violations_hard[@]}"; do
|
||||
loc="${v%% *}"; path="${v#* }"
|
||||
(( first )) || printf ','; first=0
|
||||
printf '{"loc":%s,"path":"%s"}' "$loc" "$path"
|
||||
done
|
||||
printf '],"soft":['
|
||||
first=1; for v in "${violations_soft[@]}"; do
|
||||
loc="${v%% *}"; path="${v#* }"
|
||||
(( first )) || printf ','; first=0
|
||||
printf '{"loc":%s,"path":"%s"}' "$loc" "$path"
|
||||
done
|
||||
printf ']}\n'
|
||||
else
|
||||
if (( ${#violations_soft[@]} > 0 )); then
|
||||
echo "::warning:: $((${#violations_soft[@]})) file(s) exceed soft target ($SOFT lines):"
|
||||
printf ' %s\n' "${violations_soft[@]}" | sort -rn
|
||||
fi
|
||||
if (( ${#violations_hard[@]} > 0 )); then
|
||||
echo "::error:: $((${#violations_hard[@]})) file(s) exceed HARD CAP ($HARD lines) — split required:"
|
||||
printf ' %s\n' "${violations_hard[@]}" | sort -rn
|
||||
echo
|
||||
echo "If a file legitimately must exceed $HARD lines (generated code, large data tables),"
|
||||
echo "add it to .claude/rules/loc-exceptions.txt with a one-line rationale comment above it."
|
||||
fi
|
||||
fi
|
||||
|
||||
(( ${#violations_hard[@]} == 0 ))
|
||||
55
scripts/githooks/pre-commit
Executable file
55
scripts/githooks/pre-commit
Executable file
@@ -0,0 +1,55 @@
|
||||
#!/usr/bin/env bash
|
||||
# pre-commit — enforces breakpilot-compliance structural guardrails.
|
||||
#
|
||||
# 1. Blocks commits that introduce a non-test, non-generated source file > 500 LOC.
|
||||
# 2. Blocks commits that touch backend-compliance/migrations/ unless the commit message
|
||||
# contains the marker [migration-approved] (last-resort escape hatch).
|
||||
# 3. Blocks edits to .claude/settings.json, scripts/check-loc.sh, or
|
||||
# .claude/rules/loc-exceptions.txt unless [guardrail-change] is in the commit message.
|
||||
#
|
||||
# Bypass with --no-verify is intentionally NOT supported by the team workflow.
|
||||
# CI re-runs all of these on the server side anyway.
|
||||
|
||||
set -euo pipefail
|
||||
REPO_ROOT="$(git rev-parse --show-toplevel)"
|
||||
|
||||
mapfile -t staged < <(git diff --cached --name-only --diff-filter=ACM)
|
||||
[[ ${#staged[@]} -eq 0 ]] && exit 0
|
||||
|
||||
# 1. LOC budget on staged files.
|
||||
loc_targets=()
|
||||
for f in "${staged[@]}"; do
|
||||
[[ -f "$REPO_ROOT/$f" ]] && loc_targets+=("$REPO_ROOT/$f")
|
||||
done
|
||||
if [[ ${#loc_targets[@]} -gt 0 ]]; then
|
||||
if ! "$REPO_ROOT/scripts/check-loc.sh" "${loc_targets[@]}"; then
|
||||
echo
|
||||
echo "Commit blocked: file-size budget violated. See output above."
|
||||
echo "Either split the file (preferred) or add an exception with rationale to"
|
||||
echo " .claude/rules/loc-exceptions.txt"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# 2. Migration directories are frozen unless explicitly approved.
|
||||
if printf '%s\n' "${staged[@]}" | grep -qE '(^|/)(migrations|alembic/versions)/'; then
|
||||
if ! git log --format=%B -n 1 HEAD 2>/dev/null | grep -q '\[migration-approved\]' \
|
||||
&& ! grep -q '\[migration-approved\]' "$(git rev-parse --git-dir)/COMMIT_EDITMSG" 2>/dev/null; then
|
||||
echo "Commit blocked: this change touches a migrations directory."
|
||||
echo "Database schema changes require an explicit migration plan reviewed by the DB owner."
|
||||
echo "If approved, add '[migration-approved]' to your commit message."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# 3. Guardrail files are protected.
|
||||
guarded='^(\.claude/settings\.json|\.claude/rules/loc-exceptions\.txt|scripts/check-loc\.sh|scripts/githooks/pre-commit|AGENTS\.(python|go|typescript)\.md)$'
|
||||
if printf '%s\n' "${staged[@]}" | grep -qE "$guarded"; then
|
||||
if ! grep -q '\[guardrail-change\]' "$(git rev-parse --git-dir)/COMMIT_EDITMSG" 2>/dev/null; then
|
||||
echo "Commit blocked: this change modifies guardrail files."
|
||||
echo "If intentional, add '[guardrail-change]' to your commit message and explain why in the body."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
exit 0
|
||||
26
scripts/install-hooks.sh
Executable file
26
scripts/install-hooks.sh
Executable file
@@ -0,0 +1,26 @@
|
||||
#!/usr/bin/env bash
|
||||
# install-hooks.sh — installs git hooks that enforce repo guardrails locally.
|
||||
# Idempotent. Safe to re-run.
|
||||
|
||||
set -euo pipefail
|
||||
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
HOOKS_DIR="$REPO_ROOT/.git/hooks"
|
||||
SRC_DIR="$REPO_ROOT/scripts/githooks"
|
||||
|
||||
if [[ ! -d "$REPO_ROOT/.git" ]]; then
|
||||
echo "Not a git repository: $REPO_ROOT" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
mkdir -p "$HOOKS_DIR"
|
||||
for hook in pre-commit; do
|
||||
src="$SRC_DIR/$hook"
|
||||
dst="$HOOKS_DIR/$hook"
|
||||
if [[ -f "$src" ]]; then
|
||||
cp "$src" "$dst"
|
||||
chmod +x "$dst"
|
||||
echo "installed: $dst"
|
||||
fi
|
||||
done
|
||||
|
||||
echo "Done. Hooks active for this clone."
|
||||
Reference in New Issue
Block a user