AGENTS.md

# AGENTS.md — Rules for agents (and humans) working in this repo

This repository is a **research project** with a master plan and reproducible
protocol. Before touching code or experiments, read this completely.

## 1. Context in one sentence

Empirical study of modern speculative decoding (EAGLE-3/DFlash/DSpark) on an
RTX 4060 Ti 16 GB with Gemma 4 12B and Qwen3-8B GGUF: acceptance by domain,
quantization and hardware break-even. The research documentation (thesis, gaps,
plan) lives locally in `docs/` (not versioned); live status is ALWAYS in
`STATUS.md` (local, not versioned).

## 2. Conventions

- **Language**: docs, logs and commit messages in **English**; code and
  technical metadata in **English**. Do not mix languages within one file.
- **Documentation**: markdown and session logs in `docs/`, live status in
  `STATUS.md` — all local, **not versioned**. The corpus `papers/` and its
  notes `notes/` are not versioned (regenerated locally with a download script,
  outside the repo).
- **Environment**: activate with `source scripts/spec-env.sh` (uv + CUDA in
  `~/cuda`). Never install anything with sudo; if privileges are needed, ask
  uli and wait.
- **Minimum quality before commit**: `ruff check`, `ruff format --check`,
  `pyright` with no errors on what you touched.

## 3. Git rules

- **Logical commits** (never a mega-commit); concise messages in English with a
  type prefix (`docs:`, `chore:`, `feat:`, `fix:`).
- **Do not version**: `models/`, `*.gguf`, `papers/`, `notes/`,
  `experiments/runs/`, `.venv/`, `.atl/` (see `.gitignore`).
- Do not commit regenerable artifacts (PDFs, raw runs, build logs).
- Before committing: `git status` + `git diff` to review what goes in.

## 4. Experiments (Phase 1+)

- **Never** launch a run without a viable `--resume` (incremental JSONL) unless
  explicitly decided.
- Follow the master plan protocol (§4): fixed seeds (42), documented temperature,
  target-only baseline with the SAME quantization, config.json + metrics.json per
  run in `experiments/runs/<id>/`.
- **Do not** use the full DeepSpec data cache (~38 TB); only subsamples.
- Do not change the master plan targets/decisions (§10) without uli's approval.

## 5. Sessions and handoff (mandatory)

At the end of any work session:

1. Write the session log at `docs/logs/YYYY-MM-DD-sesion-NN-asunto.md` (local
   logbook, not versioned: what was done, decisions, pending items, what is
   still running).
2. Update `STATUS.md` (local, not versioned: current phase, what is running,
   pending, next steps).
3. Save in engram (`mem_save`/`mem_session_summary`) non-obvious decisions and
   discoveries (project: `spectulative_decoding`).
4. If background processes remain (downloads, builds, runs): note them in
   STATUS.md (local) with PID and log.

A new agent opening the repo should read: `AGENTS.md` → (local `STATUS.md`,
docs and logs) before acting.

## 6. Forbidden / careful

- **Forbidden**: sudo without notice; versioning models/PDFs/runs; using the
  38 TB cache; modifying raw results; deleting another session's
  `experiments/runs/`.
- **Careful**: recompiling llama.cpp without noting the exact commit; changing
  the overnight/resume regime; discarding speedup < 1 results (they are valid
  data, not errors).