Contributing

These conventions apply to every repository in the Crest Intelligence organisation.

New to the team? Start with ONBOARDING.md — how the org is laid out, which repo is for what, and how we work. This file is the detail underneath it.

Before you start

• Read SECURITY.md. The data-handling rules are not optional.
• Repositories are private by default. Do not make one public, or copy its contents elsewhere, without an owner's sign-off.

Branching

main is the integration branch in every repo. Do not commit to it directly.

Branch from main using a typed prefix:

feat/parcel-intake-retry
fix/ec-parser-date-parsing
chore/pin-opencv
docs/methodology-playbook

Commits

Write commit subjects in the imperative mood, under 72 characters, explaining why rather than restating the diff.

Good:  Retry EC fetch on portal 502 instead of failing the parcel
Poor:  updated ec_parties.py

Pull requests

Every change reaches main through a pull request.

1. Open the PR against main and fill in the template.
2. Get at least one approving review from a core member. Add them in the Reviewers box yourself — CODEOWNERS does not auto-request on our plan.
3. Make sure CI is green.
4. Merge with Squash and merge — the only method enabled. Your branch is deleted automatically.

Keep PRs small enough to review properly. A PR that touches extraction logic, report rendering and CI at once will be sent back to be split.

Code

Python (hatad, corpus-architecture/backend) — Python 3.11+, formatted and linted with ruff. Run ruff check . and ruff format . before pushing.

TypeScript (corpus-architecture/frontend) — Next.js 14 with the App Router, strict TypeScript. Run npm run typecheck before pushing.

Do not add a dependency without saying why in the PR description. Pin versions in requirements.txt; we pin deliberately so a scraper does not break on an upstream release.

Evidence and correctness

This system produces reports people rely on to move money. Correctness beats speed.

• A claim in a report must trace to a record. If you cannot cite it, do not assert it.
• Distinguish verified, unverified and contradicted in code as carefully as the report does.
• Do not silently swallow a parse failure. A missing record is a finding, not a blank.

Questions

Open a discussion or ask in the core team channel before building something large. An hour of alignment beats a week of rework.