# Foxhunt — HFT Trading System

## Behavioral Rules

- Do what has been asked; nothing more, nothing less
- NEVER create files unless absolutely necessary
- ALWAYS prefer editing an existing file to creating a new one
- NEVER proactively create documentation files (*.md) unless explicitly requested
- NEVER save working files, text/mds, or tests to the root folder
- ALWAYS read a file before editing it
- NEVER commit secrets, credentials, or .env files

## Project Overview

Rust-based high-frequency trading system with ML-driven strategies (DQN, PPO, TFT, Mamba2), deployed on Kubernetes (Scaleway Kapsule) via Argo Workflows.

### Tech Stack

| Component | Technology |
|-----------|------------|
| Language | Rust 1.85+, Edition 2021 |
| Async | Tokio 1.40 (multi-threaded) |
| RPC | Tonic 0.14 (gRPC), tonic-web (browser gateway) |
| Database | PostgreSQL 16 (SQLx, offline mode), Redis 7, QuestDB 8.2.3 |
| ML | DQN, PPO, TFT, Mamba2 (Rust inference) |
| Frontend | React 19, TypeScript, Tailwind CSS, Vite (`web-dashboard/`) |
| Orchestration | Kubernetes + Argo Workflows |
| Build Cache | sccache (MinIO S3 backend) |
| GPU | CUDA 12.4, L40S (48GB), H100 (80GB) |

## Project Structure

| Directory | Purpose |
|-----------|---------|
| `crates/` (40 crates) | Core libs: trading engine, ML models, data, backtesting, risk mgmt |
| `services/` (8 services) | Microservices: API, Trading, ML Training, Data Acquisition, Backtesting, Broker Gateway, Trading Agent |
| `bin/fxt/` | CLI binary |
| `web-dashboard/` | React dashboard (gRPC-web) |
| `testing/` | Integration, e2e, load, stress tests |
| `infra/k8s/` | K8s manifests, Argo Workflows, network policies, monitoring |
| `infra/docker/` | Dockerfiles (ci-builder, runtime, training-runtime) |
| `scripts/` | Build, deployment, health-check, GPU scripts |
| `migrations/` | PostgreSQL migrations |
| `proto/` | Protocol Buffer definitions |
| `config/` | Configuration files and templates |

## Build & Test

```bash
# Build
cargo build --release
cargo build --profile=dev-release          # Fast iteration (thin LTO)
cargo build -p <service-name> --release    # Single service

# Test
cargo test --workspace
cargo test -p <crate-name>
cargo test --test integration

# Benchmarks
cargo bench --bench performance_regression
cargo bench --bench trading_latency
cargo bench --bench database_performance
```

- `SQLX_OFFLINE=true` — compiled SQL queries (no live DB needed for build)
- `SCCACHE_BUCKET=foxhunt-sccache` — shared compile cache

### Tiered local validation (fast dev cycle)

Three-tier funnel before cluster submit (per `docs/superpowers/specs/2026-06-02-fast-dev-cycle.md`):

| Tier | Setup | Time | What it validates |
|---|---|---|---|
| 1 (correctness) | RTX 3050, b=16, 200 steps, 1 file | ~6 sec | Kernel correctness, ISV slots, NaN |
| 1.5 (behavior) | RTX 3050, b=128, 2000+500 steps, 2 files | ~10 min | entropy, hold growth, controller stability, early Pearson |
| 2 (eval verdict) | L40S, b=1024, 20k+5k, 9 files | ~70 min | eval pnl, eval wr, regime stratification |

**Tier 1.5 data path**: `test_data/futures-baseline-mid/` (symlinks to existing MBP-10 files for fold-1 train/eval split).

```bash
./scripts/local-mid-smoke.sh           # Run Tier 1.5 mid-smoke (~10 min)
./scripts/determinism-check.sh         # Reproducibility self-test (runs mid-smoke twice, diffs final 5 rows)
python3 scripts/tier1_5_verdict.py /tmp/foxhunt-mid-smoke   # Behavioral kill verdict
```

## Deployment (Argo Workflows)

```bash
./scripts/argo-compile-deploy.sh [--branch main] [--commit <sha>]
./scripts/argo-train.sh [--model dqn|ppo|supervised]
```

- **Node pools**: `ci-compile-cpu` (compile/test), `ci-training` (L40S GPU), `ci-training-h100` (H100 GPU)
- **Training data**: PVC at `/mnt/training-data/futures-baseline`
- **Docker**: Kaniko push to Scaleway Container Registry
- **Legacy CI**: `.gitlab-ci.yml` exists but disabled (`when: never`), Argo is primary

## File Organization Rules

- NEVER save to root folder
- `/src`, `/crates` — Rust source code
- `/tests`, `/testing` — test files
- `/docs` — documentation
- `/config` — configuration
- `/scripts` — utility scripts
- `/infra` — infrastructure (K8s, Docker)

## Security Rules

- NEVER hardcode API keys, secrets, or credentials
- NEVER commit .env files or trading credentials
- Always validate input at system boundaries
- Sanitize file paths to prevent directory traversal
- Broker credentials (AMP Futures/CQG FIX 4.4) are K8s secrets — never log them

## Concurrency: 1 MESSAGE = ALL RELATED OPERATIONS

- All operations MUST be concurrent/parallel in a single message
- Use Claude Code's Task tool for spawning agents
- ALWAYS batch ALL todos in ONE TodoWrite call
- ALWAYS spawn ALL agents in ONE message via Task tool
- ALWAYS batch ALL file reads/writes/edits in ONE message
- ALWAYS batch ALL Bash commands in ONE message

## RuFlo V3 Integration

Hooks are configured in `.claude/settings.json` and run local scripts from `.claude/helpers/`. All hooks have timeouts — no network calls on the hot path.

### CLI Commands

```bash
npx ruflo@latest status                    # Check status
npx ruflo@latest hooks metrics             # View learning metrics
npx ruflo@latest hooks pretrain            # Bootstrap from repository
npx ruflo@latest hooks build-agents        # Generate agent configs
```

## important-instruction-reminders

Do what has been asked; nothing more, nothing less.
NEVER create files unless they're absolutely necessary for achieving your goal.
ALWAYS prefer editing an existing file to creating a new one.
NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
Never save working files, text/mds and tests to the root folder.