docs: update CLAUDE.md with v2-master branch structure

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 <noreply@anthropic.com>
2025-11-10 14:55:58 +01:00
parent 95e2c284af
commit 291ccf0c6a
1 changed files with 107 additions and 30 deletions
--- 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/<component>/<task-id>-<description>
 # 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 <noreply@anthropic.com>"

-# 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/<component>/<task-id>-<description>
+
+# 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