Break CI circular dependency with non-docs change

.claude/docs/managing-file-paths.md

@@ -0,0 +1,80 @@
+# Managing File Paths in Configuration Files
+
+**CRITICAL: Hardcoded paths are a major source of bugs, especially after refactors.**
+
+## Before Committing Path Changes
+
+1. **Verify the path actually exists:**
+
+   ```bash
+   ls -la <the-path-you-just-added>
+   ```
+
+2. **Test operations that use the path:**
+
+   ```bash
+   # If it's a build artifact path in package-scripts.yml:
+   yarn run prepack
+   yarn run yalc.publish
+
+   # If it's a webpack output path:
+   yarn build && ls -la <output-path>
+   ```
+
+3. **Search for ALL references to old paths if renaming:**
+   ```bash
+   # Example: if renaming node_package/ to packages/
+   grep -r "node_package" . --exclude-dir=node_modules --exclude-dir=.git
+   grep -r "packages/react-on-rails" . --exclude-dir=node_modules
+   ```
+
+## Files That Commonly Have Path References
+
+**Always check these after directory structure changes:**
+
+- `package-scripts.yml` - build artifact paths in prepack/prepare scripts
+- `package.json` - "files", "main", "types", "exports" fields
+- `webpack.config.js` / `config/webpack/*` - output.path, resolve.modules
+- `.github/workflows/*.yml` - cache paths, artifact paths, working directories
+- `lib/generators/**/templates/**` - paths in generated code
+- Documentation files - example paths and installation instructions
+
+## Post-Refactor Validation Checklist
+
+After any directory structure change, run this checklist:
+
+```bash
+# 1. Find any lingering references to old paths
+grep -r "old/path/name" . --exclude-dir=node_modules --exclude-dir=.git
+
+# 2. Verify build artifacts are in expected locations
+yarn build
+find . -name "ReactOnRails.full.js" -type f
+find . -name "package.json" -type f
+
+# 3. Test package scripts
+yarn run prepack
+yarn run yalc.publish
+
+# 4. Test clean install
+rm -rf node_modules && yarn install
+
+# 5. Run full test suite
+rake
+```
+
+## Real Example: The package-scripts.yml Bug
+
+**What happened:**
+
+- Path was changed from `node_package/lib/` to `packages/react-on-rails/lib/`
+- Later, the actual directory structure was reverted to `lib/` at root
+- But package-scripts.yml still referenced `packages/react-on-rails/lib/`
+- This caused yalc publish to fail silently for 7 weeks
+
+**How to prevent:**
+
+1. After changing directory structure, search for ALL references to old paths
+2. Always run `yarn run yalc.publish` manually to verify it works
+3. Check that paths in package-scripts.yml match actual file locations
+4. Use `ls -la <path>` to verify paths exist before committing

.claude/docs/master-health-monitoring.md

@@ -0,0 +1,64 @@
+# Master Branch Health Monitoring
+
+**CRITICAL: Master staying broken affects the entire team. Don't let it persist.**
+
+## Immediate Actions After Your PR Merges
+
+Within 30 minutes of your PR merging to master:
+
+1. **Check CI status:**
+
+   ```bash
+   # View the merged PR's CI status
+   gh pr view <your-pr-number> --json statusCheckRollup
+
+   # Or check recent master runs
+   gh run list --branch master --limit 5
+   ```
+
+2. **If you see failures:**
+   - Investigate IMMEDIATELY
+   - Don't assume "someone else will fix it"
+   - You are responsible for ensuring your PR doesn't break master
+
+## When You Discover Master is Broken
+
+1. **Determine if it's from your PR:**
+
+   ```bash
+   gh run list --branch master --limit 10
+   ```
+
+2. **Take immediate action:**
+   - If your PR broke it: Submit a fix PR within the hour, OR revert and resubmit
+   - If unsure: Investigate and communicate with team
+   - Never leave master broken overnight
+
+## Silent Failures are Most Dangerous
+
+Some failures don't show up in standard CI:
+
+- yalc publish failures
+- Build artifact path issues
+- Package installation problems
+
+**Always manually test critical workflows:**
+
+- If you changed package structure → test `yarn run yalc.publish`
+- If you changed build configs → test `yarn build && ls -la lib/`
+- If you changed generators → test `rake run_rspec:example_basic`
+
+## Understanding Workflow Reruns
+
+**Important limitation:**
+
+- Re-running a workflow does NOT change its `conclusion` in the GitHub API
+- GitHub marks a run as "failed" even if a manual rerun succeeds
+- Our CI safety checks (as of PR #2062) now handle this correctly
+- But be aware: old commits with failed reruns may still block docs-only commits
+
+**What this means:**
+
+- If master workflows fail, reruns alone won't fix the circular dependency
+- You need a new commit that passes to establish a clean baseline
+- See PR #2065 for an example of breaking the cycle

.claude/docs/testing-build-scripts.md

@@ -0,0 +1,65 @@
+# Testing Build and Package Scripts
+
+**CRITICAL: Build scripts are infrastructure code that MUST be tested manually:**
+
+## Why This Matters
+
+- The `prepack`/`prepare` scripts in package.json/package-scripts.yml run during:
+  - `npm install` / `yarn install` (for git dependencies)
+  - `yalc publish` (critical for local development)
+  - `npm publish`
+  - Package manager prepare phase
+- If these fail, users can't install or use the package
+- Failures are often silent - they don't show up in normal CI
+
+## Mandatory Testing After ANY Changes
+
+**If you modify package.json, package-scripts.yml, or build configs:**
+
+1. **Test the prepack script:**
+
+   ```bash
+   yarn run prepack
+   # Should succeed without errors
+   ```
+
+2. **Test yalc publish (CRITICAL):**
+
+   ```bash
+   yarn run yalc.publish
+   # Should publish successfully
+   ```
+
+3. **Verify build artifacts exist at expected paths:**
+
+   ```bash
+   # Check the path referenced in package-scripts.yml
+   ls -la lib/ReactOnRails.full.js
+
+   # If package-scripts.yml references packages/*, check that too
+   ls -la packages/*/lib/*.js
+   ```
+
+4. **Test clean install:**
+   ```bash
+   rm -rf node_modules
+   yarn install
+   # Should install without errors
+   ```
+
+## When Directory Structure Changes
+
+If you rename/move directories that contain build artifacts:
+
+1. **Update ALL path references in package-scripts.yml**
+2. **Test yalc publish BEFORE pushing**
+3. **Test in a fresh clone to ensure no local assumptions**
+4. **Consider adding a CI job to validate artifact paths**
+
+## Real Example: What Went Wrong
+
+In Sep 2024, we moved `node_package/` → `packages/react-on-rails/`. The path in
+package-scripts.yml was updated to `packages/react-on-rails/lib/ReactOnRails.full.js`.
+Later, the structure was partially reverted to `lib/` at root, but package-scripts.yml
+wasn't updated. This broke yalc publish silently for 7 weeks. Manual testing of
+`yarn run yalc.publish` would have caught this immediately.

.github/actions/ensure-master-docs-safety/action.yml

@@ -1,5 +1,5 @@
 name: Ensure master docs-only skips are safe
-description: Fails if the previous master commit still has failing workflow runs when current push is docs-only
+description: Prevents docs-only commits from skipping CI when previous master commit has unresolved test failures
 inputs:
   docs-only:
     description: 'String output from ci-changes-detector ("true" or "false")'

CLAUDE.md

@@ -211,12 +211,25 @@ When making changes, update the **appropriate changelog(s)**:
 **CRITICAL**: When resolving merge conflicts, follow this exact sequence:
 
 1. **Resolve logical conflicts only** - don't worry about formatting
-2. **Add resolved files**: `git add .` (or specific files)
-3. **Auto-fix everything**: `rake autofix`
-4. **Add any formatting changes**: `git add .`
-5. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+2. **VERIFY FILE PATHS** - if the conflict involved directory structure:
+   - Check if any hardcoded paths need updating
+   - Run: `grep -r "old/path" . --exclude-dir=node_modules`
+   - Pay special attention to package-scripts.yml, webpack configs, package.json
+   - **Test affected scripts:** If package-scripts.yml changed, run `yarn run prepack`
+3. **Add resolved files**: `git add .` (or specific files)
+4. **Auto-fix everything**: `rake autofix`
+5. **Add any formatting changes**: `git add .`
+6. **Continue rebase/merge**: `git rebase --continue` or `git commit`
+7. **TEST CRITICAL SCRIPTS if build configs changed:**
+   ```bash
+   yarn run prepack          # Test prepack script
+   yarn run yalc.publish     # Test yalc publish if package structure changed
+   rake run_rspec:gem        # Run relevant test suites
+   ```
 
 **❌ NEVER manually format during conflict resolution** - this causes formatting wars between tools.
+**❌ NEVER blindly accept path changes** - verify they're correct for current structure.
+**❌ NEVER skip testing after resolving conflicts in build configs** - silent failures are dangerous.
 
 ### Debugging Formatting Issues
 - Check current formatting: `yarn start format.listDifferent`
@@ -236,6 +249,18 @@ When making changes, update the **appropriate changelog(s)**:
 - **Gem-only tests**: `rake run_rspec:gem`
 - **All tests except examples**: `rake all_but_examples`
 
+## Testing Build and Package Scripts
+
+@.claude/docs/testing-build-scripts.md
+
+## Master Branch Health Monitoring
+
+@.claude/docs/master-health-monitoring.md
+
+## Managing File Paths in Configuration Files
+
+@.claude/docs/managing-file-paths.md
+
 ## Project Architecture
 
 ### Monorepo Structure