3320ef94fc
Squash of branch refactor/phase0-guardrails-and-models-split — 4 commits,
81 files, 173/173 pytest green, OpenAPI contract preserved (360 paths /
484 operations).
## Phase 0 — Architecture guardrails
Three defense-in-depth layers to keep the architecture rules enforced
regardless of who opens Claude Code in this repo:
1. .claude/settings.json PreToolUse hook on Write/Edit blocks any file
that would exceed the 500-line hard cap. Auto-loads in every Claude
session in this repo.
2. scripts/githooks/pre-commit (install via scripts/install-hooks.sh)
enforces the LOC cap locally, freezes migrations/ without
[migration-approved], and protects guardrail files without
[guardrail-change].
3. .gitea/workflows/ci.yaml gains loc-budget + guardrail-integrity +
sbom-scan (syft+grype) jobs, adds mypy --strict for the new Python
packages (compliance/{services,repositories,domain,schemas}), and
tsc --noEmit for admin-compliance + developer-portal.
Per-language conventions documented in AGENTS.python.md, AGENTS.go.md,
AGENTS.typescript.md at the repo root — layering, tooling, and explicit
"what you may NOT do" lists. Root CLAUDE.md is prepended with the six
non-negotiable rules. Each of the 10 services gets a README.md.
scripts/check-loc.sh enforces soft 300 / hard 500 and surfaces the
current baseline of 205 hard + 161 soft violations so Phases 1-4 can
drain it incrementally. CI gates only CHANGED files in PRs so the
legacy baseline does not block unrelated work.
## Deprecation sweep
47 files. Pydantic V1 regex= -> pattern= (2 sites), class Config ->
ConfigDict in source_policy_router.py (schemas.py intentionally skipped;
it is the Phase 1 Step 3 split target). datetime.utcnow() ->
datetime.now(timezone.utc) everywhere including SQLAlchemy default=
callables. All DB columns already declare timezone=True, so this is a
latent-bug fix at the Python side, not a schema change.
DeprecationWarning count dropped from 158 to 35.
## Phase 1 Step 1 — Contract test harness
tests/contracts/test_openapi_baseline.py diffs the live FastAPI /openapi.json
against tests/contracts/openapi.baseline.json on every test run. Fails on
removed paths, removed status codes, or new required request body fields.
Regenerate only via tests/contracts/regenerate_baseline.py after a
consumer-updated contract change. This is the safety harness for all
subsequent refactor commits.
## Phase 1 Step 2 — models.py split (1466 -> 85 LOC shim)
compliance/db/models.py is decomposed into seven sibling aggregate modules
following the existing repo pattern (dsr_models.py, vvt_models.py, ...):
regulation_models.py (134) — Regulation, Requirement
control_models.py (279) — Control, Mapping, Evidence, Risk
ai_system_models.py (141) — AISystem, AuditExport
service_module_models.py (176) — ServiceModule, ModuleRegulation, ModuleRisk
audit_session_models.py (177) — AuditSession, AuditSignOff
isms_governance_models.py (323) — ISMSScope, Context, Policy, Objective, SoA
isms_audit_models.py (468) — Finding, CAPA, MgmtReview, InternalAudit,
AuditTrail, Readiness
models.py becomes an 85-line re-export shim in dependency order so
existing imports continue to work unchanged. Schema is byte-identical:
__tablename__, column definitions, relationship strings, back_populates,
cascade directives all preserved.
All new sibling files are under the 500-line hard cap; largest is
isms_audit_models.py at 468. No file in compliance/db/ now exceeds
the hard cap.
## Phase 1 Step 3 — infrastructure only
backend-compliance/compliance/{schemas,domain,repositories}/ packages
are created as landing zones with docstrings. compliance/domain/
exports DomainError / NotFoundError / ConflictError / ValidationError /
PermissionError — the base classes services will use to raise
domain-level errors instead of HTTPException.
PHASE1_RUNBOOK.md at backend-compliance/PHASE1_RUNBOOK.md documents
the nine-step execution plan for Phase 1: snapshot baseline,
characterization tests, split models.py (this commit), split schemas.py
(next), extract services, extract repositories, mypy --strict, coverage.
## Verification
backend-compliance/.venv-phase1: uv python install 3.12 + pip -r requirements.txt
PYTHONPATH=. pytest compliance/tests/ tests/contracts/
-> 173 passed, 0 failed, 35 warnings, OpenAPI 360/484 unchanged
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
56 lines
2.4 KiB
Bash
Executable File
56 lines
2.4 KiB
Bash
Executable File
#!/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
|