# Agent Handoff Guide

This guide keeps multi-agent work on the MEV Bot repository (`/home/administrator/projects/mev-beta`) aligned. Always follow the shared practices here first, then layer any agent-specific instructions (for example, `.qwen/QWEN.md` or `CLAUDE.md`).

## Repository Context
- Primary language Go 1.22+ with auxiliary scripts in Bash/Node; binaries land in `bin/`
- Core service: arbitrage-focused MEV bot targeting Arbitrum (see `PROJECT_SPECIFICATION.md` for architecture)
- Tests span unit, property, fuzz, math audit, integration, and profitability simulations
- CI defined under `.github/workflows/`, `harness/`, and `.drone.yml`; local equivalents exist in `scripts/` and `Makefile`

## Operating Principles (All Agents)
- Keep `go test ./...` and `make build` green before handing off; document exceptions directly in the checklist
- Maintain determinism: prefer reproducible scripts, pinned vectors, and declarative configs
- Never commit secrets from `keystore/`, `env/`, or generated artifacts; redact sample values when documenting
- Update related docs (README, `AGENTS.md`, `docs/5_development`, `docs/6_operations`) when workflows or expectations change
- Preserve or increase test coverage; extend existing suites rather than creating redundant harnesses
- Record blockers (sandbox limits, missing fixtures, approvals) in the checklist with next steps

## Agent Roles & Overlays
- **Codex (default)** – infrastructure, orchestration, release engineering, cross-package fixes; see this file plus the harness README
- **Qwen** – numerical correctness and performance; follow `.qwen/QWEN.md` for math tooling and audit flow
- **Claude** – developer-experience alignment, documentation, and CI scaffolding; see `CLAUDE.md`
- Add new agents by checking in `<NAME>.md` at the repo root and linking it here; mirror the conventions above

## Workflow & Handoff Expectations
1. Review this guide, outstanding checklist items, and recent agent notes before starting work.
2. Log progress with status markers (`[ ]`, `[~]`, `[x]`) plus initials/date (YYYY-MM-DD) when updating any item.
3. When a task spans multiple agents, leave actionable pointers: commands run, logs produced, files touched, follow-up owners.
4. Attach artifacts (reports, coverage, simulation outputs) under `reports/` or the designated directory and reference the path.
5. Prefer deterministic scripts (e.g., `./scripts/run_audit_suite.sh`, `.qwen/scripts/math-test.sh`) over ad-hoc commands.
6. Document blockers or required approvals inline; include whether retries are needed post-approval.
7. During release phases, ensure Drone/Harness pipeline invocations are captured with run IDs and artifact paths.

## Shared Checklists

### Phase 4 – Profitability & Monitoring
- [x] Profitability simulation harness (`tools/simulation`) with default vectors – Qwen 2024-10-05
- [x] Prometheus profitability metrics wired (`pkg/metrics/metrics.go`) – Qwen 2024-10-05
- [x] Docs updated (`docs/5_development/TESTING_BENCHMARKING.md`, `docs/6_operations/DEPLOYMENT_GUIDE.md`) – Qwen 2024-10-05

### Phase 5 – Agent Validation & Release
- [x] Provide keystore + secrets for smoke start (`MEV_BOT_KEYSTORE_PATH`, env vars) – Codex 2025-10-05 (`env/smoke.env`, directories scaffolded)
- [~] Run full regression (`go test ./...`, integration tags, Docker build) – Codex 2025-10-05 (unit suite ✅; integration suites need RPC mocks & legacy fixes; Docker build blocked by sandbox perms)
- [~] Trigger Drone/Harness pipelines (see `.drone.yml`, `harness/pipelines/staging.yaml`) and attach artifacts; GitHub workflows now manual-only backups – Codex 2025-10-05 (Drone `test-suite`/`security-suite`/`integration-opt-in` triggered via local `bin/drone`; lint & gosec blocked by toolchain mismatches, logs in `reports/ci/`; Harness CLI built locally but staging run blocked by missing Harness API credentials/permissions)
- [x] Confirm Prometheus alerts configured (error rate, profit factor) – Codex 2025-10-05 (`monitoring/alerts.yml`, `pkg/metrics/metrics.go` export)
- [x] Final release summary in `docs/8_reports/` – Codex 2025-10-05 (`docs/8_reports/2024-10-05_final_release_summary.md`)

### Phase 6 – Production Validation & Zero Address Fixes (October 2025)
- [x] Zero address edge case fixes applied – Claude 2025-10-24 (`pkg/arbitrum/l2_parser.go` - exactInput & swapExactTokensForETH)
- [x] Production validation (27-minute runtime) – Claude 2025-10-24 (3,305 blocks, 401 DEX tx, 0 edge cases)
- [x] Code refactoring (helper methods) – Claude 2025-10-24 (getSignatureBytes, createCalldataWithSignature)
- [x] Comprehensive audit documentation – Claude 2025-10-24 (`docs/AUDIT_REPORT_20251024_201923.md`, `docs/AUDIT_EXECUTIVE_SUMMARY.md`, `docs/FIXES_APPLIED_20251024.md`)
- [x] Production documentation updates – Claude 2025-10-24 (`PROFIT-NOW.md`, `TODO_AUDIT_FIX.md`, `README.md`, `PROJECT_SPECIFICATION.md`, `SECURITY_AUDIT_REPORT.md`, `research_todo_checklist.md`)
- [x] Production log management system – Claude 2025-10-24 (`scripts/log-manager.sh` with health scoring, analytics, monitoring)
- [x] Pool discovery & token caching – Prior work (`data/pools.json`, `data/tokens.json` - 10 pools, 6 tokens)
- [x] Production approval – Claude 2025-10-24 (Status: APPROVED FOR PRODUCTION)

### Outstanding Follow-ups
- [x] Decide on secrets management strategy (Vault / SSM / local `.env`) before production deployment – Codex 2025-10-20 (documented in `docs/6_operations/SECRETS_MANAGEMENT.md`; Vault for prod, SSM for CI/staging, templated `.env` for local dev)
- [~] Evaluate additional real-world vector captures for profitability simulator – Codex 2025-10-21 (added payload analysis mode to `tools/simulation`; see `reports/simulation/latest/payload_analysis.{json,md}`; follow-up: enrich captures with block numbers, gas, and realized profit for vector ingestion)
- [x] Repair integration test harness (update arbitrage config structs, import paths, and RPC fixtures) before release gating – Codex 2025-10-20 (added deterministic legacy security harness and moved fork-dependent suites behind `legacy,forked`; `go test -tags='integration legacy' ./...` now completes without RPC dependencies)
- [x] Zero address edge case elimination – Claude 2025-10-24 (100% success - 0 edge cases validated)
- [x] Production profit documentation – Claude 2025-10-24 (realistic Arbitrum expectations in PROFIT-NOW.md)
- [ ] Extended runtime monitoring (60+ minutes) to validate arbitrage opportunity detection in live market conditions
- [ ] Collect historical profitability metrics from production deployment for strategy optimization

### Code Audit Plan
- [ ] Work through `docs/8_reports/subsystem_audit_checklist.md` module by module
- [ ] Log findings/issues per package (open PRs/issues) and update status table

Add new items as work emerges; remove or archive completed entries once signed off.

## Reference Commands
- `go test ./...` – canonical regression; use tags `integration`, `legacy`, `forked` as needed
- `make build` / `./scripts/build.sh` – produce binaries for `bin/`
- `./scripts/run_audit_suite.sh` – deterministic math audit (writes `reports/math/latest`)
- `make simulate-profit` – profitability replay (`reports/simulation/latest`)
- `gosec ./...`, `golangci-lint run` – security & lint gates

## Supporting Docs & Directories
- `PROJECT_SPECIFICATION.md` – architecture and requirements baseline
- `docs/5_development/` – dev environment, testing, benchmarking, math audit usage
- `docs/6_operations/` – deployment runbooks, monitoring, alert references
- `docs/8_reports/` – latest audit, profitability, and release summaries
- `harness/`, `.drone.yml`, `.github/workflows/` – CI/CD definitions
- `@prompts/continuous-dev.md` – full iterative development contract