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 <noreply@anthropic.com> 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 <noreply@anthropic.com>

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