.agent/coding_conventions.md

## Coding conventions (enforced under deadline pressure)

This repo is optimized for: **correctness, reproducibility, and not leaking labels**. Read `architecture.md` first.

## Python style (hard rules)

- **Typed dataclasses everywhere** for public API shapes (actions/observations/state).
  - Use `@dataclass(frozen=True, slots=True)` by default.
  - Public functions must be type-annotated end-to-end.
- **No untyped dicts in public APIs.** Dicts are allowed only internally (e.g., during XML parse), and must be converted to dataclasses at the boundary.
- Keep functions small. Prefer pure functions (`reward.py`) with no hidden state.

## Import ordering

1. stdlib
2. third-party
3. local modules

Within a section: alphabetical. One import per line if it improves diff clarity.

## Docstrings and naming

- Docstrings: short, imperative, include constraints (e.g., must not leak ground truth).
- Names: explicit over clever (`compute_reward`, `parse_action_xml`, `EpisodeState`).

## Error handling patterns

- **Never crash on model output.** Malformed actions must be handled gracefully.
- Raise exceptions only for programmer errors; user/model errors return structured error fields.
- Every boundary (HTTP handlers, XML parser) must be defensive:
  - validate inputs
  - clamp budgets
  - return safe defaults

## Forbidden patterns (do not do these)

- **No LLM-as-judge in reward.** Reward must be verifiable (dataset truth + keyword checks). See `architecture.md`.
- **No label leakage**: do not log, return, or print ground truth in observations, HTTP responses, or debug endpoints.
- **No hardcoded local paths** (e.g., `C:\\Users\\...`, `/home/...`). Use repo-relative paths + `pathlib`.
- **No committing data files > 5MB** without explicit team sign-off. (If necessary, use HF Datasets or remote storage.)
- **No localStorage in any UI.** If you add UI later (unlikely), store state server-side or in-memory only.
- **No adding endpoints/features after scope freeze** (midnight Saturday).

## Repo hygiene

- Prefer CLI-driven ops so teammates can reproduce quickly:
  - HF: `huggingface-cli`, `hf` (where available), `git lfs` if needed
  - GCP: `gcloud`
- Keep logs minimal. Under hackathon pressure, noisy logs hide real bugs.
- Dont vendor big artifacts in git. Link them (video, wandb, Space) from README.

## Scope creep rule (non-negotiable)

If youre tempted to add a feature that isnt required for the locked deliverables:
- Append one bullet to `FUTURE_WORK.md` (with 1-line rationale).
- Return to your current task.

## Cross-reference

- Architecture contract: `architecture.md`
- Scope and fallbacks: `project_context.md`
- Locked decisions: `decision_log.md`