# Repository Guidelines

This file is for AI coding agents working in this repository.  
Goal: make changes that are correct, deterministic, secure and compatible with the spec.

## Project Intent

- Kernite is an AI-operable policy decision gateway for write-path enforcement.
- Priorities:
  - deterministic decision output
  - minimal runtime surface (currently `dependencies = []`)
  - stable machine-readable contract for integrations
- Reference docs:
  - `README.md`
  - `docs/design-philosophy.md`

## Project Structure

- Source: `src/kernite/`
  - `cli.py`: HTTP server and routes
  - `validation.py`: request validation and normalization
  - `evaluator.py`: execute decision logic and trace hash generation
  - `core.py`: generic rule evaluation helpers
  - `reason_codes.py`: reason code dictionary
- Tests: `tests/`
- Contract docs: `docs/compatibility.md`
- Conformance vectors: `docs/conformance/v1/execute_vectors.json`
- Reason-code semantics: `docs/conformance/v1/reason_codes_v1.json`

## Contract-Critical Rules (Do Not Break)

- Stable v1 execute response fields:
  - top-level: `ctx_id`, `message`, `data`
  - decision: `data.decision`, `data.reason_codes`, `data.reasons`
  - selection/evidence: `data.policy_selection_reason_code`, `data.policy`, `data.trace_hash`
  - echo: `data.idempotency_key`
- `trace_hash` must keep canonical shape `sha256:<hex>` and deterministic canonicalization behavior.
- Existing reason-code meanings are stable once released.
- For patch/minor changes, do not mutate existing conformance vector expectations; append additive vectors only.
- If behavior intentionally diverges, add a time-bounded allowlist in tests with explicit expiry.

Read `docs/compatibility.md` before modifying execute behavior.

## API Behavior Baseline

- Health: `GET /health`
- Execute: `POST /execute`, `POST /v1/execute`
- Validate: `POST /validate/execute`, `POST /v1/validate/execute`
- Execute decisions are `approved` or `denied`.
- Validation returns machine-readable errors and normalized payload.

## Build, Test, and Local Commands

- Start server: `uv run kernite serve`
- Lint format check: `uvx ruff format --check --diff .`
- Lint: `uvx ruff check .`
- Run all tests: `uv run pytest -q`
- Run targeted tests: `uv run pytest tests/<target>.py -q`

If a command fails because environment dependencies are missing, install/sync with the repo's `uv` workflow and rerun the same command.

## Editing Guidance for Agents

- Prefer minimal, scoped patches. Do not mix unrelated refactors.
- Keep evaluation deterministic:
  - avoid non-deterministic ordering in serialized structures
  - avoid time/random-dependent output on contract fields unless explicitly designed
- Do not add runtime dependencies unless clearly justified and requested.
- Update tests with code changes in the same patch.
- When changing decision/reason behavior, update both:
  - `docs/conformance/v1/execute_vectors.json`
  - `src/kernite/contracts/v1/execute_vectors.json`
- and update relevant tests in `tests/`
- When adding or changing reason codes, update both:
  - `src/kernite/contracts/v1/reason_codes_v1.json`
  - `docs/conformance/v1/reason_codes_v1.json`

## Commit and PR Conventions

- Use Conventional Commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`.
- Keep commits focused and explain rationale in PR description.
- Use DCO sign-off (`git commit -s`).

## Security and Data Hygiene

- Never commit secrets or real credentials.
- For examples/tests/docs, use fake placeholders.
- For vulnerability handling, follow `SECURITY.md`.

## Agent Quality Bar

- Verify assumptions in code before concluding. Do not guess.
- Prefer high-confidence answers backed by repository sources.
- Before finishing, run the narrowest meaningful tests that cover your changes.
