breakpilot-compliance/CONTRIBUTING.md

Contributing to breakpilot-compliance

---

1. Getting Started

git clone https://gitea.meghsakha.com/Benjamin_Boenisch/breakpilot-compliance.git
cd breakpilot-compliance
git checkout coolify        # always base work off coolify, NOT main

Branch conventions (branch from coolify):

Prefix	Use for
feature/	New functionality
fix/	Bug fixes
chore/	Tooling, deps, CI, docs

Example: git checkout -b feature/ai-sdk-risk-scoring

---

2. Dev Environment

Each service runs independently. Start only what you need.

Go — ai-compliance-sdk

cd ai-compliance-sdk
go run ./cmd/server

Python — backend-compliance

cd backend-compliance
pip install -r requirements.txt
uvicorn main:app --reload

Python — dsms-gateway / document-crawler / compliance-tts-service

cd <service>
pip install -r requirements.txt
uvicorn main:app --reload --port <port>

Node.js — admin-compliance

cd admin-compliance
npm install
npm run dev        # http://localhost:3007

Node.js — developer-portal

cd developer-portal
npm install
npm run dev        # http://localhost:3006

All services together (local Docker)

docker compose up -d

Config lives in .env (not committed). Copy .env.example and fill in COMPLIANCE_DATABASE_URL, QDRANT_URL, QDRANT_API_KEY, and Vault tokens.

---

3. Before Your First Commit

Run all of these locally. CI will run the same checks and fail if they don't pass.

LOC budget (mandatory)

bash scripts/check-loc.sh          # must exit 0

Go lint

cd ai-compliance-sdk
golangci-lint run --timeout 5m ./...

Python lint

cd backend-compliance
ruff check .
mypy compliance/                   # only if mypy.ini exists

TypeScript type-check

cd admin-compliance
npx tsc --noEmit

Tests

# Go
cd ai-compliance-sdk && go test ./...

# Python backend
cd backend-compliance && pytest

# DSMS gateway
cd dsms-gateway && pytest test_main.py

If any step fails, fix it before committing. The git pre-commit hook re-runs check-loc.sh automatically.

---

4. Commit Message Rules

Use Conventional Commits style:

<type>(<scope>): <short summary>

[optional body]
[optional footer]

Types: feat, fix, chore, refactor, test, docs, ci.

[guardrail-change] marker — REQUIRED

Add [guardrail-change] anywhere in the commit message body (or footer) when your changeset touches any of these files:

File / path	Reason protected
.claude/settings.json	PreToolUse/PostToolUse hooks
scripts/check-loc.sh	LOC enforcement script
scripts/githooks/pre-commit	Git hook
.claude/rules/loc-exceptions.txt	Exception registry
AGENTS.*.md (any)	Per-language architecture rules

The guardrail-integrity CI job checks for this marker and fails the build if it is missing.

Valid guardrail commit example:

chore(guardrail): add exception for generated protobuf file

proto/generated/compliance.pb.go exceeds 500 LOC because it is
machine-generated and cannot be split. Added to loc-exceptions.txt
with rationale.

[guardrail-change]

---

5. Architecture Rules (Non-Negotiable)

File budget

• 500 LOC hard cap on every non-test, non-generated source file.
• The PreToolUse hook in .claude/settings.json blocks Claude Code from creating or editing files that would breach this limit.
• Exceptions require a written rationale in .claude/rules/loc-exceptions.txt plus [guardrail-change] in the commit.

Clean architecture per service

• Python (FastAPI): api → services → repositories → db.models. Handlers ≤ 30 LOC. See AGENTS.python.md.
• Go (Gin): Standard Go Project Layout + hexagonal. cmd/ is thin wiring. See AGENTS.go.md.
• TypeScript (Next.js 15): server-first, push client boundary deep, colocate _components/ + _hooks/ per route. See AGENTS.typescript.md.

Database is frozen

• No new Alembic migrations, no ALTER TABLE, no __tablename__ or column renames.
• The pre-commit hook blocks any change under migrations/ or alembic/versions/ unless the commit message contains [migration-approved].

Public endpoints are a contract

• Any change to a route path, HTTP method, status code, request schema, or response schema in backend-compliance/, ai-compliance-sdk/, dsms-gateway/, document-crawler/, or compliance-tts-service/ must be accompanied by a matching update in every consumer (admin-compliance/, developer-portal/, breakpilot-compliance-sdk/, consent-sdk/) in the same changeset.
• OpenAPI baseline snapshots live in tests/contracts/. Contract tests fail on any drift.

---

6. Pull Requests

• Target branch: coolify — never open a PR directly against main.
• Keep PRs focused; one logical change per PR.

PR checklist before requesting review:

• bash scripts/check-loc.sh exits 0
• All lint checks pass (go, python, tsc)
• All tests pass locally
• No endpoint drift without consumer updates in the same PR
• [guardrail-change] present in commit message if guardrail files were touched
• Docs updated if new endpoints, config vars, or architecture changed

---

7. Claude Code Users

This section is for AI-assisted development sessions using Claude Code.

• Always verify your branch first: git branch --show-current must return coolify. If it returns main, switch before doing anything.
• The .claude/settings.json PreToolUse hooks will automatically block Write/Edit operations on files that would exceed 500 lines. This is intentional — split the file instead.
• If the guardrail-integrity CI job fails, check that your commit message body includes [guardrail-change]. Add it and amend or create a fixup commit.
• Never use git add -A or git add . — always stage specific files by path to avoid accidentally committing .env, node_modules/, .next/, or compiled binaries.
• After every session: bash scripts/check-loc.sh must exit 0 before pushing.
• Read CLAUDE.md and the relevant AGENTS.<lang>.md before starting work on a service.