# Contributing to Orxaq

## Development Setup

```bash
git clone https://github.com/Orxaq/orxaq.git
cd orxaq
pip install -e ".[dev]"
pre-commit install
```

## Running Tests

```bash
# Full suite with coverage
pytest tests/ -v --tb=short --cov=src/orxaq --cov-report=term-missing --cov-fail-under=90

# Or use the Makefile shortcut
make test

# Quick smoke tests only
pytest tests/ -m smoke -q

# Skip slow tests
pytest tests/ -m "not slow" -q
```

Coverage must stay at or above 90%. The CI pipeline enforces this gate.

## Linting

```bash
# Check for violations
ruff check src/ tests/

# Auto-fix what can be fixed
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/
```

Pre-commit hooks run ruff automatically on every commit. To run all hooks manually:

```bash
pre-commit run --all-files
```

## Commit Messages

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(kernel): add soliton scoring to WorldDAG edges
fix(credit): correct PD bounds clamping for edge cases
docs: update CLI reference in README
test(fabric): add lineage tracker coverage for multi-hop paths
refactor(intelligence): extract BIC computation to helper
```

Format: `type(scope): description`

- **type**: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`, `ci`
- **scope**: module name (`kernel`, `credit`, `fabric`, `intelligence`, `orchestration`, `experiences`, `enterprise`, `validation`, `cli`)
- **description**: imperative mood, lowercase, no period, under 72 characters

## Pull Request Process

1. Branch from `main`: `git checkout -b feat/your-feature`
2. Make your changes. Write tests. Ensure coverage does not decrease.
3. Run the full quality gate: `make check`
4. Push and open a PR against `main`.
5. PRs are squash-merged. The PR title becomes the commit message.

## Architecture Decision Records

Significant design decisions are documented as ADRs in `docs/adr/`. If your change involves an architectural choice (new dependency, new abstraction, changed interface), write an ADR before implementing. See `docs/adr/README.md` for the template.

## Project Structure

```
src/orxaq/
  kernel/          Ring 1: types, WorldDAG, audit, crypto, plugins
  credit/          Ring 2: ontology, PD model, CECL, scenarios, fair lending, synthetic
  fabric/          Ring 2: connectors, schema, profiler, quality, lineage, catalog
  intelligence/    Ring 3: PC, GES, consensus, independence, validation, simulator
  orchestration/   Ring 4: LLM providers (vLLM, Anthropic, OpenAI), registry, router
  experiences/     Ring 5: API server, dashboard, DAG editor, skins, static assets
  enterprise/      Enterprise: health checks, environment config
  validation/      Validation: metrics, pipeline, report, synthetic data generator
  cli.py           CLI entry point (20+ subcommands)
  integration.py   OrxaqEngine facade
tests/
  kernel/          Kernel tests
  credit/          Credit risk tests
  fabric/          Data fabric tests
  intelligence/    Causal discovery + simulator tests
  orchestration/   Provider, registry, router tests
  experiences/     API, server, editor, skin tests
  enterprise/      Health check + config tests
  validation/      Validation pipeline tests
deploy/
  helm/            Kubernetes Helm chart
docs/
  adr/             Architecture Decision Records
  api/             API reference (per module)
  architecture/    Architecture overview
  guides/          User guides (CLI, credit risk, etc.)
```

Rings depend only on lower-numbered rings. Ring 1 (Kernel) has zero external dependencies.

## Security

See [SECURITY.md](SECURITY.md) for vulnerability reporting guidelines.
