# Repository Guidelines

## Project Structure & Module Organization

The Python package lives in `src/quality/`, split into `cli/` for the `claude-quality` entry point, `core/` domain
models, `analyzers/` and `detection/` engines, and `utils/` helpers. Hook integrations used by Claude Code run from
`hooks/`, with shared settings in `hooks/claude-code-settings.json`. Tests focus on `tests/hooks/` for the hook
lifecycle and leverage fixtures in `tests/hooks/conftest.py`. Repository-level configuration is centralized in
`pyproject.toml` and the `Makefile`.

## Build, Test, and Development Commands

Run `make venv` once to create a Python 3.12 virtualenv and activate it before development. Use `make install-dev` to
install the package in editable mode with dev extras via `uv` and register pre-commit hooks. Daily checks:

- `make lint` → `ruff check` + `ruff format --check`
- `make typecheck` → strict `mypy` against `src/`
- `make test` / `make test-cov` → `pytest` with optional coverage
- `make check-all` → lint + typecheck + tests
  For ad hoc analysis, `make analyze` runs `claude-quality full-analysis src/ --format console`.

## Coding Style & Naming Conventions

Code targets Python 3.12+, uses 4-space indentation, and follows `ruff` with an 88-character line width. Prefer
expressive `snake_case` module and function names, `PascalCase` for classes, and `CONSTANT_CASE` for constants. Strict
`mypy` is enforced, so fill in type hints and avoid implicit `Any`. Format using `ruff format`; do not mix formatters.
Keep docstrings concise and use Google-style docstrings when they add clarity.

## Testing Guidelines

`pytest` drives the suite with primary coverage under `tests/hooks/`. Group new tests alongside related hook modules and
name files `test_<feature>.py` with test functions `test_*`. The CI configuration enforces `--cov=code_quality_guard`
and `--cov-fail-under=80`; run `make test-cov` before opening a PR to confirm coverage. For focused runs, target a path
such as `pytest tests/hooks/test_pretooluse.py -k scenario`.

## Commit & Pull Request Guidelines

Commit messages follow Conventional Commit semantics (`feat:`, `fix:`, `chore:`). Example:
`feat: tighten posttool duplicate detection thresholds`. Before pushing, run `pre-commit run --all-files` and
`make check-all`; include the output or summary in the PR description. PRs should link relevant issues, describe
behavioral changes, and attach HTML coverage or console snippets when functionality changes. Screenshots are expected
when hook output formatting shifts or CLI UX changes.