# FlareDB Feature Constitution

## Core Principles

### I. Test-First (NON-NEGOTIABLE)
- Write tests before implementation for new functionality.
- Follow Red-Green-Refactor; do not merge untested code.
- All critical paths require unit tests; integration tests required when services/protocols change.

### II. Reliability & Coverage
- CI must run `cargo test` (or equivalent) for all touched crates.
- Integration verification must cover cross-service interactions when contracts change.
- Regressions on previously passing tests are not acceptable.

### III. Simplicity & Readability
- Prefer standard crates over bespoke solutions; avoid unnecessary complexity (YAGNI).
- Code must be self-explanatory; add concise comments only for non-obvious logic.
- Keep APIs minimal and coherent; avoid naming drift.

### IV. Observability
- Services must log structured, human-readable errors; fatal errors exit non-zero.
- gRPC/CLI surfaces should emit actionable diagnostics on failure.

### V. Versioning & Compatibility
- Protocol and API changes must call out compatibility impact; breaking changes require explicit agreement.
- Generated artifacts must be reproducible (lockfiles or pinned versions where applicable).

## Additional Constraints
- Technology stack: Rust stable, gRPC via tonic/prost, RocksDB for storage, tokio runtime.
- Nix flake is the canonical dev environment; commands should respect it when present.

## Development Workflow
- Tests before code; integration tests when touching contracts or cross-service logic.
- Code review (human or designated process) must confirm constitution compliance.
- Complexity must be justified; large changes should be broken down into tasks aligned with user stories.

## Governance
- This constitution supersedes other practices for this feature; conflicts must be resolved by adjusting spec/plan/tasks, not by ignoring principles.
- Amendments require an explicit update to this document with rationale and date.

**Version**: 1.0.0 | **Ratified**: 2025-11-30 | **Last Amended**: 2025-11-30