> **Note:** [`CLAUDE.md`](CLAUDE.md) is canonical for thresholds, release details, and the full research-compute guidance. This file is the shorter derivative for non-Claude AI agents.

# Repository Guidelines

## Agent Workflow
- Start with the shipped-behavior docs before editing: `README.md` for product surface, `CONTRIBUTING.md` for the local quality contract, and the area-specific doc for the subsystem you are touching (`evals/README.md`, `slurm/README.md`, `docs/mcp-reference.md`, `docs/configuration.md`, etc.).
- Keep repository exploration targeted. `evals/cases/` is large, and `evals/artifacts/`, `evals/results/`, `evals/swebench_runs/`, `.llmdebug/`, and `.benchmarks/` are generated trees. Prefer focused `rg`/file reads over bulk scans.
- When behavior, CLI/API usage, runbooks, or generated documentation blocks change, update the corresponding docs in the same patch.

## Debug Snapshot Workflow
- On any failing test or command, inspect `.llmdebug/latest.json` first, or run `llmdebug show --json --detail context`.
- Read the crash frame, exception message, locals, array shapes, and captured git/env context before editing.
- Form 2-4 ranked hypotheses from the evidence, then apply the smallest fix that matches the best-supported hypothesis.
- Re-run after each fix; avoid speculative multi-change patches.
- If the snapshot shows the symptom but not the cause, add targeted instrumentation such as `snapshot_section("stage_x")`, regenerate the snapshot, and continue the hypothesis loop.
- Useful CLI helpers:
  - `llmdebug show --detail full`
  - `llmdebug show --detail context`
  - `llmdebug show previous`
  - `llmdebug diff`

## Project Structure & Architecture
- `src/llmdebug/`: package code.
  - Capture, schema, and presentation: `capture.py`, `config.py`, `serialize.py`, `output.py`, `compact_keys.py`, `detail_filter.py`, `error_categories.py`, `hypotheses.py`, `_debug_session.py`, `_snapshot_loader.py`, `_formatting.py`, `_presentation.py`, `_json.py`, `snapshot_types.py`, `snapshot_diff.py`, `toon_encoder.py`.
  - RCA and persistence: `rca_state.py`, `rca_transitions.py`, `rca_engine.py`, `rca_backend.py`, `rca_identity.py`, `gates.py`, `state_db.py`, `rca_store.py`.
  - Interfaces and contracts: `cli.py`, `mcp_server.py`, `mcp_git_context.py`, `mcp_rca.py`, `mcp_contract.py`, `mcp_types.py`, `pytest_plugin.py`, `jupyter_plugin.py`, `middleware.py`.
  - Runtime integrations and support: `hooks.py`, `redaction_policy.py`, `git_context.py`, `coverage_context.py`, `async_context.py`, `log_capture.py`, `_warnings.py`.
- `evals/`: benchmark and analysis harness.
  - Runners and summaries: `run_eval.py`, `analyze_results.py`, `eval_summary.py`, `eval_two_pass_summary.py`, `report_run_metrics.py`, `select_cases.py`, `validate_cases.py`.
  - Adaptive policy and contracts: `adaptive_online_policy.py`, `adaptive_budget_online_policy.py`, `policy_feature_scaling.py`, `stage_a_contract.py`.
  - Support packages: `patchers/`, `importers/`, `swebench/`, `configs/`, `docker/`, `cases/`.
- `tests/`: pytest suite for package behavior, RCA flows, MCP tools, eval harnesses, quality-contract checks, and SWE-Bench helpers.
- `docs/`: user docs, protocol notes, runbooks, and research notes.
- `scripts/`: helper utilities such as benchmark comparison, HAICore SSHFS, and official SWE-Bench scoring wrappers.
- `slurm/`: HAICore/cluster entrypoints, smoke tests, resume-chain helpers, and bundle collectors.
- `quality/`: coverage baselines and other quality-policy assets.
- Generated artifacts should not be committed: `.llmdebug/`, `.benchmarks/`, `evals/artifacts/`, `evals/results/*.jsonl`, `evals/swebench_runs/`, `reports/`, `dist/`, `coverage.xml`, `coverage.json`, `htmlcov/`.

### Architecture guardrails
- Keep entrypoint modules (`cli.py`, `mcp_server.py`, `pytest_plugin.py`, `jupyter_plugin.py`, `middleware.py`) thin.
- Keep reusable logic in composable core modules; avoid reverse imports from interface layers into core.
- Preserve the RCA split: pure/domain logic in `rca_engine.py` and `rca_transitions.py`, persistence in `state_db.py` and `rca_store.py`, adapters at the boundaries.
- Prefer clear seams around capture, serialization, snapshot presentation, RCA state transitions, and eval patcher/importer boundaries instead of cross-cutting edits.

## Build, Test, and Development Commands
Use `uv` for environments and direct tool execution. Use `just` for the repo’s standard wrappers.

### Quick checks
```bash
uv sync --group dev
just lint
just typecheck
just test-quick
```

Equivalent direct commands:
```bash
uv run ruff check src tests
uv run ruff format --check src tests
uv run pyright
uv run pytest -x -q
```

### Full local quality pass
```bash
just check
just quality
```

`just check` runs lint, typecheck, and coverage-gated tests. `just quality` is the shared quality contract used by CI/release automation.

Key direct commands:
```bash
uv run ruff check src tests evals
uv run ruff format src tests evals
uv run pytest --cov=src/llmdebug --cov-branch --cov-report=term-missing --cov-report=xml --cov-report=json --cov-fail-under=85
uv run python scripts/quality/check_coverage_no_regression.py --coverage-json coverage.json --baseline-json quality/coverage_baseline.json
uv run diff-cover coverage.xml --compare-branch=origin/main --fail-under=80
uv run bandit -c pyproject.toml -r src/llmdebug
uv run vulture src/llmdebug vulture_whitelist.py --min-confidence 90
uv run deptry src/llmdebug
uv run pip-audit
uv run radon cc -s -a src/llmdebug
uv run xenon --max-absolute C --max-modules C --max-average B src/llmdebug
uv run python -m evals.doc_sync --check
uv build --no-sources
```

### Formatting, docs, and benchmarking
```bash
just format
just docs-check
just docs-sync
just bench-capture
just bench-capture-compare
```

### Eval helpers
```bash
uv run python -m evals.validate_cases --schema-only
just eval-summary <run_id>
just eval-two-pass-summary <baseline_run_id> <rescue_run_id>
```

## CI Contract
- `.github/workflows/ci-cd.yml` runs `just lint`, `just typecheck`, and `just test-no-cov` across Python 3.10, 3.11, 3.12, and 3.13.
- `.github/actions/run-quality-contract/action.yml` runs `just quality` on Python 3.13 and adds `just diff-coverage` on pull requests.
- Always run CI/CD locally before pushing to `main`.
- If a change is version-sensitive, mirror CI locally with `PYTHON_VERSION=<version> just <recipe>`.

## Server Command Convention (`pueue`)
- When suggesting commands for a server, prefer queueing them:
  - `pueue add -- <command>`
  - `pueue status`
  - `pueue log <task_id>`
  - `pueue follow <task_id>`
- If you intentionally suggest a foreground command instead, say that the direct run is deliberate.

## Coding Style & Naming
- Python 3.10+, 4-space indentation, max line length 100.
- Ruff config lives in `pyproject.toml` and enforces `E`, `W`, `F`, `I`, `UP`, `B`, `SIM`, `C4`, `RUF`, `PERF`, and `FURB`.
- Pyright runs in `strict` mode for `src/llmdebug`.
- Prefer precise type annotations on new or changed APIs.
- Naming conventions: `snake_case` for modules/functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
- Keep patches focused and local; prefer adapters or helper seams over broad refactors.

## Testing & Quality Expectations
- Framework: `pytest` with `testpaths = ["tests"]`.
- Add a regression test for each bug fix or behavior change when feasible.
- Use async tests when touching coroutine paths.
- Coverage floor is `>=85%`; branch coverage must not regress versus `quality/coverage_baseline.json`; changed-line coverage is `>=80%` on PRs.
- Treat `bandit`, `deptry`, `pip-audit`, `vulture`, `radon`, `xenon`, docs drift, and SLURM script validation as part of the normal review surface when relevant.
- When touching generated documentation blocks or release/changelog surfaces, run `just docs-check`; run `just docs-sync` when the generated content needs to be refreshed.
- When touching `slurm/` scripts or HAICore runbooks, run `just slurm-check`.
- When touching capture/serialization hot paths, benchmark-sensitive code, or perf claims, run `just bench-capture`.

## Eval & Research Notes
- Read `evals/README.md` before changing the eval harness, cases, importers, patchers, or reporting code.
- The main eval conditions are `traceback_only`, `with_snapshot`, `with_snapshot_structured`, `adaptive_gated`, and `adaptive_llm_discretion`.
- Keep eval orchestration, patcher backends, importer logic, adaptive-policy logic, and SWE-Bench tooling loosely coupled; these pieces are reused across multiple flows.
- `evals/README.md` contains an auto-generated case inventory block; refresh it with `python -m evals.doc_sync --write` when case metadata changes.
- SWE-Bench Lite support lives under `evals/swebench/` and uses a two-plane workflow: HAICore/Enroot generation plus Docker-based official scoring. Follow `evals/README.md`, `slurm/README.md`, and `docs/haicore_enroot_swebench_lite_runbook.md`.
- Common SLURM helpers:
  - `slurm/check_env_gguf_eval.sh`
  - `slurm/run_gguf_smoke.sh`
  - `slurm/check_env_swebench_lite.sh`
  - `slurm/run_swebench_lite_smoke.sh`
  - `slurm/submit_gguf_resume_chain.sh <RUN_ID> 4`
  - `slurm/submit_swebench_lite_resume_chain.sh <RUN_ID> 4`

## Release & PR Guidance
- Releases use `python-semantic-release`; version sources are `pyproject.toml` and `src/llmdebug/__init__.py`.
- CI and release automation live in `.github/workflows/ci-cd.yml`, `.github/workflows/release.yml`, and `.github/actions/run-quality-contract/action.yml`.
- Prefer Conventional Commits: `feat:`, `fix:`, `perf:`, `docs:`, `test:`, `chore:`.
- Use `feat!:` or a `BREAKING CHANGE:` footer for incompatible changes.
- Helpful release commands:
```bash
uv run semantic-release version --noop
uv run semantic-release version --print
```
- Before opening a PR or preparing a release, run `just check` at minimum and `just quality` for tooling, docs, eval-harness, or release-path changes.
