Add critical lessons learned and corrections to Phase 2 plan

Based on Phase 2 implementation experience, add crucial guidance:

CORRECTIONS:
- Fix git subtree command (remove --squash to preserve individual commits)
- Correct branch workflow (create branch FIRST before any work)
- Update duration estimate (2-3 days, 1-2 with lessons learned)

LESSONS LEARNED:
1. Branch management workflow corrections
2. Git subtree best practices
3. Complete linting tool configuration requirements
4. Yalc vs file: dependency management approach
5. Multiple dummy apps that need updates
6. CircleCI optimization strategies
7. Local dependency management patterns

These lessons will significantly speed up future monorepo merger implementations.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Correct Phase 2 git strategy to use filter-repo approach

Update merger plan to reflect the actual commands used:

STRATEGY CHANGE:
- Replace git subtree approach with git filter-repo + merge
- Use git filter-repo --to-subdirectory-filter for better file history
- Use git merge --allow-unrelated-histories for clean integration

BENEFITS OF FILTER-REPO APPROACH:
- Better file history browsing with git log --follow
- Cleaner history integration compared to subtree prefixing
- No issues with path-based git operations
- Easier to browse pro file history with no problems

This approach was actually used in the implementation and provides
superior file history preservation and browsing experience.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: AbanoubGhadban

docs/MONOREPO_MERGER_PLAN.md

@@ -144,9 +144,9 @@ react_on_rails/ (monorepo root)
 
 ---
 
-### Phase 2: Git Subtree Merger (Keep Original Structure)
+### Phase 2: Git Repository Merger (Keep Original Structure)
 
-#### PR #2: Merge react_on_rails_pro via Git Subtree + Fix CI
+#### PR #2: Merge react_on_rails_pro via Git Filter-Repo + Fix CI
 
 **Branch:** `merge-pro-subtree-with-ci`
 **Target:** react_on_rails repository
@@ -159,18 +159,36 @@ react_on_rails/ (monorepo root)
 
 **Git Strategy:**
 
+⚠️ **CRITICAL: Create feature branch FIRST before any work!**
+
 ```bash
-# Add react_on_rails_pro as remote
-git remote add pro-origin https://github.com/shakacode/react_on_rails_pro.git
+# 1. FIRST: Create and checkout feature branch
+git checkout -b merge-pro-subtree-with-ci
+
+# 2. Clone and prepare pro repository with filter-repo (better for file history browsing)
+git clone https://github.com/shakacode/react_on_rails_pro.git /tmp/react_on_rails_pro
+cd /tmp/react_on_rails_pro
+git filter-repo --to-subdirectory-filter react_on_rails_pro
+
+# 3. Add the prepared pro repo as remote and merge
+cd /path/to/react_on_rails
+git remote add pro-origin /tmp/react_on_rails_pro
 git fetch pro-origin
+git merge pro-origin/master --allow-unrelated-histories
 
-# Merge using subtree (preserves history)
-git subtree add --prefix=react_on_rails_pro pro-origin/main --squash
+# 4. Push branch and create PR
+git push -u origin merge-pro-subtree-with-ci
 ```
 
+**Why filter-repo instead of subtree:**
+
+- Better file history browsing
+- Cleaner history integration compared to subtree prefixing
+- No issues with path-based git operations
+
 **Tasks:**
 
-- [x] Execute git subtree merge into `react_on_rails_pro/` directory
+- [x] Execute git filter-repo + merge into `react_on_rails_pro/` directory
 - [x] **CRITICAL: Update CI to run tests for both packages**
 - [x] Keep GitHub Actions for core package tests
 - [x] Keep CircleCI for pro package tests (temporarily)
@@ -230,7 +248,7 @@ After the initial merge, the following CI adjustments may be needed:
 
 **Success Criteria:** ✅ **ALL CI jobs pass for both core and pro packages independently**
 
-**Estimated Duration:** 3-5 days
+**Estimated Duration:** 2-3 days (with lessons learned above: 1-2 days)
 
 **Risk Level:** High (first major structural change)
 
@@ -241,6 +259,31 @@ After the initial merge, the following CI adjustments may be needed:
 - Verify no pro files accidentally ended up in MIT-licensed directories during the merge
 - Both CI systems (GitHub Actions + CircleCI) must pass independently
 
+**Critical Lessons Learned (Phase 2 Implementation):**
+
+1. **Branch Management**: ALWAYS create the feature branch BEFORE starting any work, not after commits
+2. **Git Merge Strategy**: Use `git filter-repo --to-subdirectory-filter` + `git merge --allow-unrelated-histories` instead of subtree for better file history browsing
+3. **Linting Tool Configuration**: ALL linting tools must exclude pro directory:
+   - Update `.rubocop.yml` with `'react_on_rails_pro/**/*'` exclusion
+   - Update `eslint.config.ts` with `'react_on_rails_pro/'` exclusion
+   - Update `.prettierignore` with `react_on_rails_pro/` exclusion
+   - Update `knip.ts` with `'react_on_rails_pro/**'` in ignore patterns
+4. **Local Dependencies**: Use yalc for JS packages, path references for Ruby gems:
+   - Add `preinstall` scripts to all package.json files that need local react-on-rails
+   - Use `link-source` scripts to build and publish packages with yalc
+   - Avoid `file:` paths in package.json - use `link:.yalc/package-name` instead
+5. **Multiple Dummy Apps**: Don't forget to update ALL dummy apps:
+   - `spec/dummy/` (main dummy app)
+   - `react_on_rails_pro/spec/dummy/` (pro dummy app)
+   - `react_on_rails_pro/spec/execjs-compatible-dummy/` (ExecJS dummy app)
+6. **CircleCI Optimization**: When using yalc with preinstall hooks:
+   - Remove build-core-package job (handled by preinstall scripts)
+   - Remove workspace sharing (yalc handles package distribution)
+   - Keep existing cache strategy for performance
+7. **Dependency Management**: Update both Ruby and JS dependencies to use local versions:
+   - Ruby: `path: "../.."` in gemspec and development dependencies
+   - JS: `yalc add --link package-name` in preinstall hooks
+
 ---
 
 ### Phase 3: Pre-Monorepo Structure Preparation