Reframe NextRails.next? teaching: Gemfile primacy + three-tier pattern

[JuanVqz]

Closes #18.

Follow-up to #17. That PR closed #2 with a minimum-scope example swap (replaced the fixture_path / serialize coder: deprecation-only examples with a genuine two-sided breaking change). During review of #17, a larger structural problem surfaced: the skill's SKILL.md Pattern section and references/code-patterns.md jumped straight into app-code NextRails.next? branching as the default teaching, which overstates how often the reader should reach for it. Rails's deprecate-then-remove policy means the replacement API almost always backports to the current version, so unconditional migration is the correct fix for most adjacent-minor boundaries. This PR implements the reframe explicitly.

Separately: next_rails v1.5.0 (released 2026-04-02) shipped parallel-CI-native DeprecationTracker support. The previous references/deprecation-tracking.md documented a 25-line manual Ruby merge script that is now obsolete. This PR modernizes that file to use the v1.5.0 pattern (node_index: + deprecations merge --delete-shards).

Summary of changes

Gemfile-primacy reframe

• CLAUDE.md — added invariant Add CHANGELOG.md and align SKILL.md with rails-upgrade #8: "prefer a single backport/forwardport shim over scattered conditionals when the version gap spans an application layer or affects roughly 20+ call sites".
• dual-boot/SKILL.md Pattern — first illustration is now the Gemfile if next? ; gem 'rails', '~> 7.1.0' ; else ; gem 'rails', '~> 7.0.0' ; end version pin (the canonical, always-required conditional). App-code branching is introduced as the exception. The ignored_columns example is retained as the Tier 2 illustration paired with a respond_to? WRONG counter-example.
• dual-boot/references/code-patterns.md — rewritten around the three-tier decision framework with cleanup semantics per tier.

Three-tier decision framework

Tier	Technique	When
1	Unconditional migration	Both Rails versions accept the new form (typical Rails deprecation case).
2	NextRails.next? conditional at the call site	New API doesn't exist on current (or old API raises on next). Smaller gaps (up to ~20 call sites).
3	Backport / forwardport shim	Same gap spans an application layer (all controllers, all mailers) or affects ~20+ call sites.

• Tier 2 canonical example: ignorable gem's ignore_columns → native ignored_columns= at Rails 4.2 → 5.0 (from Replace deprecation examples with genuine breaking changes #17).
• Tier 3 canonical example: ActionController::Parameters#values backport at Rails 7.0 → 7.1, verified against Don't delegate ActionController::Parameters#values to hash rails/rails#44816. params.values changed from Array<Hash> to Array<ActionController::Parameters> in 7.1; a single initializer-level shim makes the 7.0 side return the 7.1 shape so all call sites stay identical across both versions.

Cleanup covers all three tiers

dual-boot/workflows/cleanup-workflow.md — added a new Step 3 "Delete Backport / Forwardport Shim Files (Tier 3 cleanup)". Existing Step 2 covers per-call-site else-branch removal (Tier 2). Tier 1 needs nothing. Grep pattern provided for finding shim files; verification rubric distinguishes Tier-3 shim files (guard wraps a module/class redefinition) from Tier-2 call-site branches (guard wraps a single call or config).

Two-phase setup workflow

dual-boot/workflows/setup-workflow.md — restructured from a single-phase setup into explicit Phase 1 (preparatory, no Rails version hop yet) and Phase 2 (dual-boot, the Rails version hop):

Phase 1:

1. Verify deprecation warnings not silenced (now a pointer to references/deprecation-tracking.md, removing duplication).
2. Check for existing Gemfile.next.
3. Add next_rails at Gemfile root.
4. Run next_rails --init.
5. Configure DeprecationTracker. Interactive branch: local/single-process gets the plain config; parallel CI gets the node_index: config and the deprecations merge --delete-shards fan-in step.
6. Capture deprecation inventory (DEPRECATION_TRACKER=save).
7. Fix current-side deprecations unconditionally (Tier 1 only, no NextRails.next? yet).

Phase 2:
8. Configure Gemfile with if next? version conditional.
9. Identify and pin incompatible gems using bundle_report compatibility --rails-version=<target> (a command provided by next_rails).
10. Install dependencies for both versions (lockfile-copy trick preserved).
11. Verify both sides boot and run tests.
12. Fix two-sided breakage using Tier 2 / Tier 3.
13. Commit.

next_rails v1.5.0 modernization

dual-boot/references/deprecation-tracking.md — replaced the 25-line manual Ruby merge script with the v1.5.0 parallel-CI-native pattern:

RSpec.configure do |config|
  if ENV["DEPRECATION_TRACKER"]
    DeprecationTracker.track_rspec(
      config,
      node_index: ENV["CI_NODE_INDEX"]
    )
  end
end

# Save phase (each parallel node)
DEPRECATION_TRACKER=save CI_NODE_INDEX=$NODE bundle exec rspec <subset>

# Merge phase (runs once after all nodes finish)
deprecations merge --delete-shards

# Compare phase (each parallel node)
DEPRECATION_TRACKER=compare CI_NODE_INDEX=$NODE bundle exec rspec <subset>

Platform-specific env var mapping included (CircleCI → CIRCLE_NODE_INDEX, Buildkite → BUILDKITE_PARALLEL_JOB, GitLab → CI_NODE_INDEX, Semaphore → SEMAPHORE_JOB_INDEX). Minimum version requirement (next_rails >= 1.5.0) documented in both setup-workflow.md and references/deprecation-tracking.md.

Also added a last-resort grep fallback at the bottom of deprecation-tracking.md for apps where DeprecationTracker cannot be configured (loses structure, compare mode, and regression gating — use the tracker when possible).

Workflow separation in the basic-setup walkthrough

dual-boot/examples/basic-setup.md — added a "Before You Start: Resolve Current-Version Deprecations" section that frames current-version deprecation resolution as a Tier 1 prerequisite, not a step inside dual-boot fixing. Step 6 rescoped to genuine two-sided breakage only. Explicit: do not fix next-version deprecations here — those belong to the preparatory phase of the next upgrade.

Other

• CI setup is now explicitly documented as optional — local-only dual-boot is equally valid via manual two-suite invocation.
• All pointers to deprecation-resolution workflow cite dual-boot's own references/deprecation-tracking.md, keeping this PR self-contained and forward-compatible whether or not rails-upgrade PR #31 lands.

Parent branch

Branched off feature/issue-2-better-examples (PR #17). Merge order: #17 first, then rebase this branch onto main if needed.

Out of scope (deferred or rejected)

• Multi-hop upgrades — stays out. Follows the FastRuby.io methodology: one adjacent-minor at a time.
• Deprecation-tracking as separate skill scope — flagged for later consideration; not a blocker.
• README.md Key Principle expansion — stays at the ignored_columns conditional from Replace deprecation examples with genuine breaking changes #17.
• v1.4.x fallback for next_rails — require v1.5.0+; older users should upgrade.

[etagwerker]

@JuanVqz I think we need to have a longer conversation about this skill.

When I envisioned this skill, this is what I had in mind:

===

Why Dual-Boot?

Dual-booting is a core part of the FastRuby.io upgrade methodology:

• Quickly switch between dependency sets for debugging
• Run test suites against both versions
• Deploy backwards-compatible changes to production before the version bump
• Catch compatibility issues early in CI
• Allows you to gradually deploy versions of key dependencies (e.g. 10% of the traffic will now use the target version of Rails)

===

In this PR I see a whole section about this:

Before You Start: Resolve Current-Version Deprecations

I believe that goes beyond the scope of this skill.

My vision for this skill is to keep it as tight as possible to this:

• Quickly switch between dependency sets for debugging
• Run test suites against both versions
• Catch compatibility issues early in CI
• Allows you to gradually deploy versions of key dependencies (e.g. 10% of the traffic will now use the target version of Rails)

So maybe we need to drop this to avoid contributor and Claude's confusion:

• Deploy backwards-compatible changes to production before the version bump

I'd be fine if we make this skill more about instructing Claude how to use next_rails in development, test, CI, and production, and not so much about fixing deprecation warnings (I think this should be in the rails upgrade skill)

Thoughts?

[JuanVqz]

@JuanVqz I think we need to have a longer conversation about this skill.

When I envisioned this skill, this is what I had in mind:

===

Why Dual-Boot?

Dual-booting is a core part of the FastRuby.io upgrade methodology:

• Quickly switch between dependency sets for debugging
• Run test suites against both versions
• Deploy backwards-compatible changes to production before the version bump
• Catch compatibility issues early in CI
• Allows you to gradually deploy versions of key dependencies (e.g. 10% of the traffic will now use the target version of Rails)

===

In this PR I see a whole section about this:

Before You Start: Resolve Current-Version Deprecations

I believe that goes beyond the scope of this skill.

My vision for this skill is to keep it as tight as possible to this:

• Quickly switch between dependency sets for debugging
• Run test suites against both versions
• Catch compatibility issues early in CI
• Allows you to gradually deploy versions of key dependencies (e.g. 10% of the traffic will now use the target version of Rails)

So maybe we need to drop this to avoid contributor and Claude's confusion:

• Deploy backwards-compatible changes to production before the version bump

I'd be fine if we make this skill more about instructing Claude how to use next_rails in development, test, CI, and production, and not so much about fixing deprecation warnings (I think this should be in the rails upgrade skill)

Thoughts?

I'm open to talk about this. Ping me when you can.