From 291ccf0c6a8a181ebd92b3d00147e4ac43376761 Mon Sep 17 00:00:00 2001 From: Administrator Date: Mon, 10 Nov 2025 14:55:58 +0100 Subject: [PATCH] docs: update CLAUDE.md with v2-master branch structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updated project guidance to reflect V2 foundation completion: Branch Structure: - v2-master (production, protected) - v2-master-dev (development, protected) - feature/v2-prep (archived, foundation complete) - feature/v2/* (feature branches from v2-master-dev) Branch Hierarchy: v2-master ← v2-master-dev ← feature/v2/* Updated Sections: - Project Status: V2 Foundation Complete ✅ - Git Workflow: New branch structure and workflow - Example Workflow: Updated to use v2-master-dev - What TO Do: Reflects foundation completion - Key Files: Added V2 foundation files (100% coverage) - Current Branches: New section documenting branch structure - Contact and Resources: Updated with completion status Workflow: 1. Create feature branch from v2-master-dev 2. Implement with 100% test coverage 3. Run make validate locally 4. PR to v2-master-dev (CI/CD enforces coverage) 5. Merge v2-master-dev → v2-master for production Foundation Status: - 3,300+ lines (1,500 implementation, 1,800 tests) - 100% test coverage (enforced) - CI/CD fully configured - Ready for protocol parser implementations 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 137 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 107 insertions(+), 30 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 25b03d3..331994b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,14 +2,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -## Project Status: V2 Architecture Planning +## Project Status: V2 Foundation Complete ✅ -This repository is currently in **V2 planning phase**. The V1 codebase has been moved to `orig/` for preservation while V2 architecture is being designed. +This repository has completed **V2 foundation implementation** with 100% test coverage. The V1 codebase has been moved to `orig/` for preservation. **Current State:** - V1 implementation: `orig/` (frozen for reference) -- V2 planning documents: `docs/planning/` -- Active development: Not yet started (planning phase) +- V2 planning documents: `docs/planning/` (complete) +- V2 foundation: `pkg/` (✅ complete with 100% test coverage) +- Active development: Ready for protocol parser implementations ## Repository Structure @@ -214,6 +215,26 @@ go test ./tests/load/... -v ## Git Workflow +### Branch Structure + +**V2 Production & Development Branches:** + +``` +v2-master # Production branch for V2 (protected) +v2-master-dev # Development branch for V2 (protected) +feature/v2-prep # Planning and foundation (archived) +feature/v2/* # Feature branches for development +``` + +**Branch Hierarchy:** +``` +v2-master (production) + ↑ + └── v2-master-dev (development) + ↑ + └── feature/v2/* (feature branches) +``` + ### Branch Strategy (STRICTLY ENFORCED) **ALL V2 development MUST use feature branches:** @@ -225,31 +246,36 @@ feature/v2//- # Examples: feature/v2/parsers/P2-002-uniswap-v2-base feature/v2/cache/P3-001-address-index -feature/v2/validation/P4-001-validation-rules +feature/v2/arbitrage/P5-001-path-finder ``` **Branch Rules:** -1. ✅ **ALWAYS** create feature branch from `feature/v2-prep` -2. ✅ **NEVER** commit directly to `feature/v2-prep` or `master-dev` +1. ✅ **ALWAYS** create feature branch from `v2-master-dev` +2. ✅ **NEVER** commit directly to `v2-master` or `v2-master-dev` 3. ✅ Branch name MUST match task ID from `07_TASK_BREAKDOWN.md` 4. ✅ One branch per atomic task (< 2 hours work) 5. ✅ Delete branch after merge +6. ✅ Merge feature → v2-master-dev → v2-master **Example Workflow:** ```bash -# 1. Create feature branch -git checkout feature/v2-prep -git pull origin feature/v2-prep +# 1. Create feature branch from v2-master-dev +git checkout v2-master-dev +git pull origin v2-master-dev git checkout -b feature/v2/parsers/P2-002-uniswap-v2-base # 2. Implement task P2-002 # ... make changes ... # 3. Test with 100% coverage (REQUIRED) -go test ./pkg/parsers/uniswap_v2/... -coverprofile=coverage.out -# MUST show 100% coverage +make test-coverage +# MUST show 100% coverage or CI/CD will fail -# 4. Commit +# 4. Run full validation locally +make validate +# All checks must pass + +# 5. Commit with conventional format git add . git commit -m "feat(parsers): implement UniswapV2 parser base structure @@ -265,11 +291,21 @@ Tests: 15/15 passing 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude " -# 5. Push and create PR +# 6. Push and create PR to v2-master-dev git push -u origin feature/v2/parsers/P2-002-uniswap-v2-base -# 6. After merge, delete branch +# 7. Create PR on GitHub targeting v2-master-dev +# Wait for CI/CD to pass (100% coverage enforced) + +# 8. Merge PR and delete feature branch +git checkout v2-master-dev +git pull origin v2-master-dev git branch -d feature/v2/parsers/P2-002-uniswap-v2-base + +# 9. When ready for production release +git checkout v2-master +git merge --no-ff v2-master-dev +git push origin v2-master ``` ### Commit Message Format @@ -317,35 +353,76 @@ fix: parser bug - ❌ Allow zero addresses or zero amounts to propagate ### What TO Do -- ✅ Read `docs/planning/00_V2_MASTER_PLAN.md` before starting +- ✅ Review foundation implementation in `pkg/` before adding parsers - ✅ Follow task breakdown in `07_TASK_BREAKDOWN.md` -- ✅ Write tests before implementation (TDD) +- ✅ Write tests before implementation (TDD - MANDATORY) - ✅ Use strict validation at all layers - ✅ Add comprehensive logging and metrics - ✅ Fix root causes, not symptoms +- ✅ Always create feature branches from `v2-master-dev` +- ✅ Run `make validate` before pushing (100% coverage enforced) ## Key Files to Review -### Planning Documents +### Planning Documents (Complete ✅) - `docs/planning/00_V2_MASTER_PLAN.md` - Complete V2 architecture +- `docs/planning/01_MODULARITY_REQUIREMENTS.md` - Component independence +- `docs/planning/02_PROTOCOL_SUPPORT_REQUIREMENTS.md` - 13+ DEX protocols +- `docs/planning/03_TESTING_REQUIREMENTS.md` - 100% coverage enforcement +- `docs/planning/04_PROFITABILITY_PLAN.md` - Sequencer strategy & ROI +- `docs/planning/05_CI_CD_SETUP.md` - Complete pipeline documentation - `docs/planning/07_TASK_BREAKDOWN.md` - Atomic task list (99+ hours) -- `orig/README_V1.md` - V1 documentation and known issues + +### V2 Foundation (Complete ✅ - 100% Coverage) +- `pkg/types/` - Core types (SwapEvent, PoolInfo, errors) +- `pkg/parsers/` - Parser factory with routing +- `pkg/cache/` - Multi-index pool cache (O(1) lookups) +- `pkg/validation/` - Validation pipeline with rules +- `pkg/observability/` - Logging & Prometheus metrics ### V1 Reference Implementation -- `orig/pkg/events/parser.go` - Monolithic parser (to be replaced) -- `orig/pkg/monitor/concurrent.go` - Arbitrum monitor (to be enhanced) -- `orig/pkg/pools/discovery.go` - Pool discovery (cache to be multi-indexed) -- `orig/pkg/arbitrage/detection_engine.go` - Arbitrage detection (to be improved) +- `orig/pkg/events/parser.go` - Monolithic parser (reference) +- `orig/pkg/monitor/concurrent.go` - Arbitrum monitor (reference) +- `orig/pkg/pools/discovery.go` - Pool discovery (reference) +- `orig/pkg/arbitrage/detection_engine.go` - Arbitrage detection (reference) + +### Documentation +- `README.md` - Project overview and quick start +- `CLAUDE.md` - This file (project guidance) +- `docs/V2_IMPLEMENTATION_STATUS.md` - Implementation progress +- `Makefile` - Build automation commands +- `.golangci.yml` - Linter configuration (40+ linters) + +## Current Branches + +### Production & Development +- **v2-master** - Production branch for V2 (protected, stable) +- **v2-master-dev** - Development branch for V2 (protected, stable) +- **feature/v2-prep** - Planning and foundation (archived, complete) + +### Active Development Pattern +```bash +# Always branch from v2-master-dev +git checkout v2-master-dev +git pull origin v2-master-dev +git checkout -b feature/v2//- + +# Merge back to v2-master-dev via PR +# Merge v2-master-dev to v2-master when ready for production +``` ## Contact and Resources -- V2 Planning: `docs/planning/` -- V1 Reference: `orig/` -- Architecture diagrams: In `00_V2_MASTER_PLAN.md` -- Task breakdown: In `07_TASK_BREAKDOWN.md` +- **V2 Foundation:** `pkg/` (✅ Complete - 100% coverage) +- **V2 Planning:** `docs/planning/` (✅ Complete - 7 documents) +- **V1 Reference:** `orig/` (Frozen for reference) +- **CI/CD:** `.github/workflows/v2-ci.yml` (✅ Configured) +- **Build Tools:** `Makefile` (✅ Ready - `make validate`) +- **Git Hooks:** `.git-hooks/` (✅ Install with `./scripts/install-git-hooks.sh`) --- -**Current Phase**: V2 Planning -**Next Step**: Begin Phase 1 implementation (Foundation) -**Estimated Time**: 12-13 weeks for complete V2 implementation +**Current Phase:** ✅ V2 Foundation Complete (100% Coverage) +**Next Step:** Phase 2 - Protocol Parser Implementations +**Foundation:** 3,300+ lines of code (1,500 implementation, 1,800 tests) +**Status:** Production-ready infrastructure, ready for parsers