GEMINI.md

# CommitGuard - Project Context & Instructions

This file provides the foundational context and operational mandates for the **CommitGuard** project, a Meta OpenEnv RL environment for commit-time vulnerability detection.

##  Project Overview
CommitGuard is a specialized RL environment designed to train LLM agents (primarily **Llama-3.2-3B-Instruct**) to identify exploitable vulnerabilities in single-file code commits. It uses **Reinforcement Learning from Verifiable Rewards (RLVR)**, where rewards are grounded in dataset truth (Devign) rather than LLM judgment.

- **Goal:** Close the asymmetry between AI-paced code generation and human-paced security review.
- **Core Framework:** Meta OpenEnv (v0.2.3+).
- **Training Algorithm:** GRPO via TRL + Unsloth.
- **Dataset:** Preprocessed Devign (C-based commits, <80 LOC).

##  Building and Running

### Environment Server
The server is built with FastAPI and can be run locally or via Docker.
- **Install:** `pip install -e .`
- **Run Local:** `server` (Runs on `http://localhost:8000`)
- **Run Docker:** `docker build -t commitguard . && docker run -p 8000:8000 commitguard`
- **Health Check:** `curl http://localhost:8000/health`

### Training & Evaluation
- **Train (GRPO):** `python scripts/train_grpo.py`
- **Baseline Curve:** `python scripts/run_and_plot_baseline.py --episodes 200`
- **Test:** `pytest` (Standard Python testing)

##  Development Conventions & Mandates

### 1. The "No-Leak" Rule (Critical)
The agent must **NEVER** see ground truth labels (`is_vulnerable`, `cwe`, etc.).
- **Constraint:** Observations and HTTP responses must never contain label fields.
- **Verification:** `tests/test_no_leak.py` must remain green at all times.

### 2. Action Format (XML-Tagged)
Models must emit actions in XML format to ensure robust parsing.
- **Structure:** `<action><action_type>...</action_type>...</action>`
- **Types:** `request_context`, `analyze`, `verdict`.

### 3. Systematic Documentation (`.agent/`)
This project uses a structured `.agent/` directory for internal state and contracts. Always consult these before changes:
- `.agent/project_context.md`: Single source of truth for project state.
- `.agent/architecture.md`: Technical contracts and schemas.
- `.agent/test_contracts.md`: Merge-blocking requirements.

### 4. Deadline Operations (Hackathon Mode)
- **Scope Freeze:** Midnight Saturday IST. No new features after this point.
- **Pivots:** If technical blockers arise (e.g., OOM, slow queues), immediately use the pre-approved fallbacks documented in `prd.md` and `.agent/project_context.md`.

##  Directory Structure
- `commitguard_env/`: Core environment logic, FastAPI server, and reward modeling.
- `scripts/`: Training entrypoints, preprocessing scripts, and GCE runbooks.
- `data/`: Dataset placeholders (`devign_filtered.jsonl`) and CWE mapping.
- `plots/`: Generated reward curves and performance artifacts.
- `tests/`: Smoke tests, reward validation, and leak detection.
- `.agent/`: High-priority architectural and process documentation.

##  Key Endpoints
- `POST /reset`: Initialize episode, returns diff + available files.
- `POST /step`: Submit XML action, returns `{observation, reward, done, info}`.
- `GET /health`: Server status.
- `GET /state`: Episode metadata (safe for agent logs).