engrava: Instructions file for Claude Code

CLAUDE.md — engrava

This is a public repository (engrava) — Graph memory database for AI agents.

Assume every commit message, PR title, PR body, branch name, code comment, and docstring is world-visible. Public-safe by default.

Context

Aspect	Value
License	MIT
Primary language	python 3.11+
Default branch for PRs	dev
Release flow	Conventional Commits → semantic-release
Contribution model	issues + PRs on GitHub

Repository-specific rules

• Public API stability: no breaking changes within X.Y.x patch range.
• Default storage backend: SQLite (others via extensions).
• Quality gate: ruff ALL + mypy strict + 90% test coverage.

Code quality — zero-compromise bar

This is production code maintained to a high quality bar. A feature is not "done" until every point below holds:

• Linting — ruff check clean, ruff format --check clean, no rule disables without a justifying comment.
• Typing — mypy --strict clean. No bare Any. No # type: ignore without a justifying inline comment.
• Coverage — 90% minimum, enforced by --cov-fail-under=90. TDD preferred; tests are first-class code.
• Docstrings — Google-style on every public symbol (params, returns, raises, examples).
• Domain modelling — concrete types per concept, no catch-all dicts, no god objects.
• Errors — typed exceptions; never bare except; never swallow errors silently.
• No shortcuts — no TODO/FIXME/HACK in production code; open an issue instead. No dead code. No magic strings.
• Secrets — never hard-code API keys; use env vars or config objects; never log secrets.

Run locally before opening a PR

pip install -e ".[dev]"
ruff check src/ examples/ scripts/ tests/
ruff format --check src/ examples/ scripts/ tests/
mypy --strict src/
pytest --cov --cov-fail-under=90

Testing conventions (python)