opencode-ruby-upgrader 0.1.8 → 0.1.9

package/PRIVACY.md

@@ -8,4 +8,6 @@ Reports may be staged into local checkpoint commits. Review them before committi
 
 Dependency installation, tests, and Rails tooling execute project-controlled code with your local user permissions after confirmation. Use an isolated environment for repositories you do not trust.
 
+The advisory infrastructure review reads version pins and workflow files inside the current worktree (`.ruby-version`, `.tool-versions`, `.mise.toml`, `Gemfile`, `Gemfile.lock`, `Dockerfile`, `.github/workflows/`), and the dashboard computes it locally on each request. It performs no network requests and stores nothing beyond the file and version values already present in those files. Because the findings are recomputed rather than recorded, they never enter a report or commit as durable evidence.
+
 Preparing an isolated runtime creates local Docker containers, a dedicated network, and pulled images that persist after the run finishes; nothing is uploaded and no port is published to your host. Those resources are labelled with the run ID and a SHA-256 hash of the worktree path, never the path itself. That hash exists only on the Docker resources — it is deliberately kept out of `.ruby-upgrades/` so that committing your upgrade evidence does not publish a guessable fingerprint of your filesystem path. Validation recomputes the hash from the current worktree and compares it against the live labels. Validation receipts written under `.ruby-upgrades/runs/` also record ephemeral Docker identifiers (container IDs, network ID, and image IDs) for traceability of the isolated run; these are local environment metadata, not personal data. Remove containers/networks with `docker rm`/`docker network rm` using the names recorded in `.ruby-upgrades/runtime.json`, and remove pulled images separately if you want the disk space back.

package/README.md

@@ -91,7 +91,7 @@ Use `/ruby-upgrade --dry-run` for a no-write inventory and proposed migration as
 The agent has completed a real end-to-end migration against a public fixture: [`ruby2-rails4-bootstrap-heroku`](https://github.com/lilla021/ruby2-rails4-bootstrap-heroku) (BSD-2-Clause) moved from **Ruby 2.4.10 / Rails 4.2.11.3** to **Ruby 3.4.10 / Rails 7.1.6** across 15 receipt-backed hops. Every hop was validated by `bundle exec rspec` in an isolated Docker container, then committed as a local checkpoint before the next hop began.
 
 - [Upgrade pull request](https://github.com/lilla021/ruby2-rails4-bootstrap-heroku/pull/1) — the full migration: 19 commits, one per reviewed step, with lint and spec checks currently passing on GitHub Actions.
-- [Evidence ledger](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/E2E_EVIDENCE.md) — every hop's validation receipt, commit SHA, and the fixes the migration required.
+- [Evidence ledger](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.9/E2E_EVIDENCE.md) — every hop's validation receipt, commit SHA, and the fixes the migration required.
 
 This proves the workflow works on a genuinely old, real-world Rails stack. It does not claim every upgrade is safe — see [Safety model](#safety-model) for what the agent refuses to do without you, and [Product limits](#product-limits) for what it cannot prove.
 
@@ -139,11 +139,19 @@ Every run has a generated JSON record and Markdown companion under `.ruby-upgrad
 
 As an example, here is one such run rendered in the dashboard — per-hop summaries, test metrics, and citation links. The full process and per-hop detail live in the run reports themselves:
 
-![Example of the local evidence dashboard](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.6/docs/dashboard.png)
+![Example of the local evidence dashboard](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.9/docs/dashboard.png)
 
 The same reports open as a vault — each run is a Markdown note paired with its JSON record:
 
-![Example vault view: run reports as paired Markdown and JSON notes](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.6/docs/vault.png)
+![Example vault view: run reports as paired Markdown and JSON notes](https://raw.githubusercontent.com/lilla021/opencode-ruby-upgrader/v0.1.9/docs/vault.png)
+
+### Infrastructure review (advisory)
+
+Each report and the dashboard also carry a read-only review of the infrastructure the upgrade may have made inconsistent: Ruby version pins in `.ruby-version`, `.tool-versions`, `.mise.toml`, `Gemfile`, and `Dockerfile`, CI workflows that do not yet test the new target, and the Bundler version recorded in `Gemfile.lock`.
+
+These are advisory and never block a commit. The agent validates your app inside an isolated container; it has no access to your CI config, deploy host, or platform dashboard, so it cannot know what your production runtime actually uses. A version pin that deliberately lags the app is legitimate in many repositories, so every finding states the evidence it was read from and asks you to confirm it. Where a value cannot be read with confidence — an unparseable Dockerfile base image, an unfamiliar CI matrix shape — the tool stays silent rather than guessing.
+
+The dashboard recomputes these on every request from the current worktree instead of storing them in the report. A report describes what happened during that run; these findings describe the repo as it stands now, and a frozen inference would misrepresent the second as the first.
 
 Launch the local-only dashboard from the repository worktree:
 
@@ -151,10 +159,35 @@ Launch the local-only dashboard from the repository worktree:
 npx opencode-ruby-upgrader dashboard
 ```
 
-It binds exclusively to `127.0.0.1` on an ephemeral port and remains in the foreground until you stop it with Ctrl-C. The read-only dashboard displays valid Ruby and Rails-bridge reports plus locally discoverable checkpoint commits; it never changes reports, Git state, or uploads code.
+It binds exclusively to `127.0.0.1` on an ephemeral port and remains in the foreground until you stop it with Ctrl-C. The read-only dashboard displays valid Ruby, Rails-bridge, and Bundler-bridge reports plus locally discoverable checkpoint commits; it never changes reports, Git state, or uploads code.
 
 The dashboard identifies local checkpoint commits from trailers embedded in those commits. Before the final push, inspect them locally with `git log`, `git show`, and the dashboard; after you push, the same individual commits are available for GitHub review.
 
+## When a prerequisite blocks the hop
+
+A Ruby upgrade occasionally cannot cross a version boundary on its own. Two cases are handled, and both work the same way: the Ruby run becomes terminal, and a separately scoped bridge run takes over the prerequisite change.
+
+### Rails bridge
+
+If a resolved Rails version blocks the next Ruby hop, that Ruby run becomes terminal and a separate Rails-bridge run takes over. See the [Rails bridge lifecycle](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.9/docs/rails-bridge.md) reference.
+
+### Bundler bridge
+
+Your `Gemfile.lock` records the Bundler that wrote it under `BUNDLED WITH`, and Bundler switches to that version automatically. So when an upgrade moves Ruby forward, an older pinned Bundler is what breaks — not the other way round. The official compatibility guide is a table of *minimum floors* (Bundler 2.5 requires Ruby >= 3.0, 2.6 requires >= 3.1, 2.7 and 4.0 require >= 3.2), not fixed pairings: Ruby simply ships a matching Bundler as its default.
+
+If your pin sits below the researched floor for the target Ruby, the Ruby run becomes terminal and a separately scoped Bundler bridge takes over, exactly like the Rails bridge. Approving it records the floor, the rationale, and the official citation in the run evidence:
+
+```bash
+npx opencode-ruby-upgrader record-bundler-bridge --report <run>.json \
+  --ruby-from 3.3 --ruby-to 3.4 --bundler-from 2.4.17 --bundler-to 2.5.22 \
+  --minimum-bundler 2.5 --rationale "Bundler 2.4 predates Ruby 3.4 support." \
+  --citation "Bundler compatibility with Ruby|https://guides.rubygems.org/bundler-compatibility/"
+```
+
+A bridge cannot be approved for a pin that already clears the floor, so this cannot block a hop for no reason. The bridge run then researches a contiguous Bundler ladder (`begin-bundler-bridge`, `record-bundler-research`), and a hop is recorded only when the rewritten `BUNDLED WITH` pin **and** the Bundler that actually executed the tests both match the target. Because Bundler 4.0 follows 2.7 directly, the ladder may cross that boundary in a single hop.
+
+Full lifecycle detail: [docs/bundler-bridge.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.9/docs/bundler-bridge.md).
+
 ## Recovery
 
 Each active run holds a local lock. To stop for review or manual work, transition it to `paused`; that releases the lock without marking the migration complete. Resume the existing report rather than starting a second migration:
@@ -165,8 +198,6 @@ opencode-ruby-upgrader resume --report .ruby-upgrades/runs/<run>.json
 
 `complete`, `blocked`, and `paused` runs release their lock. For other blockers, inspect the report and use the documented transition/resume path.
 
-If a resolved Rails version blocks the next Ruby hop, that Ruby run becomes terminal and a separate Rails-bridge run takes over. See the [Rails bridge lifecycle](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/docs/rails-bridge.md) reference.
-
 To undo a completed hop, use the reviewable local history: `git revert <hop-sha>`. Do not use reset, rebase, or force-push as routine migration recovery.
 
 ## Troubleshooting
@@ -202,7 +233,7 @@ The credential scanner is heuristic: it recognizes common token formats and quot
 
 No telemetry, no analytics, and no report uploads. Migration evidence is written only under `.ruby-upgrades/` in the current worktree — run reports under `.ruby-upgrades/runs/` and nonsecret runtime metadata in `.ruby-upgrades/runtime.json` — and the dashboard binds to `127.0.0.1` only. Reports may contain target versions, branch names, commit SHAs, changed-file names, dependency source origins, citations, and bounded validation metadata — absolute local paths and recognized credentials are redacted, but redaction is best-effort. Prepared Docker containers, networks, and images stay on your machine and are labelled with the run ID and a one-way hash of the worktree path, never the path itself.
 
-Full detail in [PRIVACY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/PRIVACY.md). To report a vulnerability, see [SECURITY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.6/SECURITY.md).
+Full detail in [PRIVACY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.9/PRIVACY.md). To report a vulnerability, see [SECURITY.md](https://github.com/lilla021/opencode-ruby-upgrader/blob/v0.1.9/SECURITY.md).
 
 ## Contributing
 

package/RELEASE_NOTES.md

@@ -1,5 +1,44 @@
 # opencode-ruby-upgrader — release notes
 
+## v0.1.9 — advisory infrastructure review and the Bundler bridge
+
+Every run already reported that a container-validated upgrade is not a deployed upgrade. v0.1.9 makes that concrete, and then lets you act on one of the findings: when a Ruby upgrade is blocked by a Bundler that cannot run the target, the Ruby run becomes terminal and a separately scoped Bundler bridge takes over, mirroring the existing Rails bridge.
+
+### Infrastructure review (advisory)
+
+- New advisory findings for stale Ruby version pins (`.ruby-version`, `.tool-versions`, `.mise.toml`, `Gemfile`, `Dockerfile`), CI workflows that do not yet test the upgraded target, and the Bundler version recorded in `Gemfile.lock` under `BUNDLED WITH`. Each finding carries the file and value it was read from, a stated basis (`observed` vs `review`), and a remediation that asks rather than instructs.
+- These never gate anything. The agent validates the app inside an isolated container and has no access to your CI config, deploy host, or platform dashboard. A version pin that deliberately lags the app is legitimate in many repositories, so a finding that blocked a commit would be wrong as often as it was right.
+- Silence on ambiguity. An unparseable Dockerfile base image is reported as unread rather than as a version mismatch, and CI inspection only reports Ruby versions visible as plain scalars, because workflow matrix shapes vary too much to parse reliably. Reporting nothing beats guessing.
+- The dashboard recomputes findings per request from the live worktree and stores nothing in the report. A report describes what happened during that run; these describe the repo as it stands now, and persisting an inference as durable evidence would misrepresent the second as the first.
+
+### The Bundler bridge
+
+- `record-bundler-bridge` requires a researched minimum floor, a rationale, and the official citation, and records all three in run evidence. The bridge can only be approved when the recorded pin is genuinely below that floor.
+- `begin-bundler-bridge` and `record-bundler-research` produce a separate report linked back to the blocked Ruby run, with a contiguous Bundler ladder. Bundler 4.0 follows 2.7 directly (there was no 3.x series), so that boundary is a valid single hop; without it a project on 2.4 could never reach 4.0 through a reviewed ladder.
+- `record-executed-bundler-iteration` records a hop only when the rewritten `BUNDLED WITH` pin **and** the Bundler version that actually executed the tests both match the target. This is the honest evidence gate for a bridge whose output is a file change rather than a reviewable generator receipt, and it reuses the runtime Bundler attestation rather than trusting the lockfile alone.
+- `commit-bundler-hop` commits only when the recorded pin agrees with the hop target, and requires `Bundler-Bridge-Ruby-Report` so the linkage survives in Git history.
+
+### Behaviour correction
+
+The premise this was built on was wrong in an instructive way. "Ruby 4 requires Bundler 4" is not a constraint: the official table gives *minimum floors*, and each Ruby release merely ships a matching pair as its default. The compatibility risk runs the other way — an old Bundler pin breaks when Ruby moves forward — so the bridge is the mirror image of the Rails bridge, where the framework lags the Ruby. Both exist because something in the project cannot cross the hop alone.
+
+### No hardcoded compatibility table
+
+`src/bundler-compat.js` deliberately stores no versions. The tool performs no network requests, so it cannot look up which Bundler supports which Ruby, and a baked-in table would silently rot at the next series release. The floor arrives the same way Rails and Ruby facts already do — supplied by the agent as cited research at the moment the bridge is approved — and only the comparison arithmetic lives locally, because that has to be deterministic for an approval to be defensible.
+
+### Scope of change
+
+The Bundler bridge is implemented as a data variation of the existing bridge machinery rather than a third parallel code path. Bridge-specific behaviour is selected by a `bridge` parameter in the commit gate and a bridge-kind prefix in checkpoint trailers, which keeps the `reportType` branches from doubling for every future bridge type.
+
+### Evidence
+
+Unit suite 80/80, covering the floor comparison, the 2.7→4.0 boundary, ladder contiguity, bridge scoping, terminality, and the pin/runtime agreement gate, plus advisory findings against real application shapes: a project pinning 3.3.4 across four files and a workflow on 3.3.4 yields all four findings; after the pins are updated, the stale findings disappear while the Bundler note remains, since that one is a confirmation rather than a detected defect. A repository with no version files produces no findings, and a `FROM my-registry.internal/ruby:latest` base produces no version mismatch. Both real-container smokes pass against real `mysql:8.4` and `postgres:16-alpine`, each asserting a passing RSpec receipt, a secret-free persisted manifest, and clean teardown.
+
+### Known limitations
+
+- A Bundler bridge is never raised automatically. The advisory review points at the pin, but deciding whether it needs a bridge requires the researched floor, which only the agent can supply. That judgment stays explicit by design.
+- CI workflow inspection reads only Ruby versions visible as plain scalars. Unusual matrix shapes are left unreported rather than guessed at.
+
 ## v0.1.8 — real-adapter detection and PostgreSQL container evidence
 
 v0.1.7 shipped database detection that had only ever been tested against hand-written fixtures. Running it against real Rails applications found three wrong answers, one of them silent. This release fixes detection and closes the container-evidence gap for the default adapter.

package/agents/ruby-upgrade.md

@@ -14,12 +14,14 @@ You own a careful Ruby runtime migration. Be decisive on routine fixes and trans
 - Parse user controls before work: `--dry-run`, `--target <version>`, and `--stop-after-hop`. Run `opencode-ruby-upgrader inventory`, `opencode-ruby-upgrader supply-chain`, and `opencode-ruby-upgrader git-capabilities` first. Pause for explicit review on shallow clones, sparse checkout, submodules, or LFS configuration. If the project is unsupported or has no recognized test adapter, stop with the detected evidence and ask for a test command; do not invent one. After official research pins the target, initialize the durable run with `opencode-ruby-upgrader begin --target <version>` (append `--dry-run` or `--stop-after-hop` when requested). Use only the returned report path for this run.
 - Drive the durable state machine, not prose alone: record research with `record-research`, then transition `initialized → inventory_complete → research_complete`; record each complete evidence-backed hop only with `record-executed-iteration` (or `record-executed-rails-iteration`), transition to `hop_validated`, and use the returned checkpoint SHA when transitioning to `committed`. Exactly one checkpoint is required before the next iteration. Repeat per hop. Use `paused` to stop safely for user review/manual work (it releases the lock); `complete` is only valid once the pinned target is reached. Use `blocked` only with evidence and an actionable option. For an isolated legacy runtime, ask once for approval to apply the planned Ruby declaration edit and then run `prepare-target-runtime --ruby <x.y.z> --report <the run path you just resumed>` before `docker-bundle-rspec`: it creates isolated Docker resources, installs Node and Bundler 2.4.22, runs `bundle install`, and creates the isolated Rails test database when applicable. The isolated test database is PostgreSQL unless the project declares MySQL through `mysql2`, in which case the runtime prepares an isolated MySQL server; the engine is detected from the project's own declarations, so do not guess or pass `--database` on your own. If preparation reports that both MySQL and PostgreSQL were detected, stop and present that conflict with your evidence and ask the user to choose the engine once, then rerun with their answer. Execute preparation with the longest supported shell timeout (at least 15 minutes), not a default short timeout. Do not ask the user for a report path, container name, or environment variables. The persisted nonsecret runtime manifest binds labeled app and database containers to the selected run and worktree; `docker-bundle-rspec` executes only the fixed inner argv `bundle exec rspec`. Prepared Docker resources persist after the run ends; report the container and network names from the manifest so the user can remove them, and never remove containers or networks that the tool did not create for this run.
 - If the next Ruby hop is incompatible with the resolved Rails version, do not edit Rails as part of the Ruby hop. Cite the official compatibility evidence, explain the required Rails from/to versions, and obtain explicit approval before running `record-framework-bridge --report <report-path> --ruby-from <version> --ruby-to <version> --rails-from <version> --rails-to <version> --rationale <text> --citation 'title|https://...'`. Then transition the Ruby run to `blocked` and start `begin-rails-bridge --ruby-report <blocked-ruby-report>`. In that separate report, research contiguous Rails-minor hops with `record-rails-research`, record each passing hop with `record-executed-rails-iteration` including reviewed `bin/rails app:update` evidence, transition to `hop_validated`, and checkpoint only with `commit-rails-hop`. Start a fresh Ruby run only after the Rails bridge is complete.
+- If the project's `Gemfile.lock` records a `BUNDLED WITH` version below the researched minimum Bundler for the target Ruby, treat the pinned Bundler -- not Ruby itself -- as the blocker. Do not edit the lockfile's pin by hand. Consult the official compatibility guide at `https://guides.rubygems.org/bundler-compatibility/` and cite it: it lists minimum Ruby floors per Bundler series, so a higher Bundler supports a wider range of Rubies and an *older* pin is what breaks when Ruby moves forward. Obtain explicit approval before running `record-bundler-bridge --report <report-path> --ruby-from <version> --ruby-to <version> --bundler-from <version> --bundler-to <version> --minimum-bundler <version> --rationale <text> --citation 'title|https://...'`. Then transition the Ruby run to `blocked` and start `begin-bundler-bridge --ruby-report <blocked-ruby-report>`. In that separate report, research contiguous Bundler-series hops with `record-bundler-research --ladder <v1,v2,...>` (a direct 2.7 to 4.0 hop is valid because no Bundler 3.x series exists), rewrite the pin with `bundle lock --bundler <version>` inside the isolated runtime, and record each passing hop with `record-executed-bundler-iteration`; that hop is rejected unless both the rewritten `BUNDLED WITH` pin and the Bundler that executed the tests match the target. Transition to `hop_validated` and checkpoint only with `commit-bundler-hop`. Start a fresh Ruby run only after the Bundler bridge is complete. Never approve a bridge for a pin that already clears the researched floor.
 - Rails `app:update` executes with conflict-skipping semantics so existing application configuration is never overwritten noninteractively. Review every generated file before final tests. If a pending result is unsafe or superseded, revert only that unvalidated hop and run `discard-pending-app-update --report <report-path> --reason <review finding>`; the discarded digest remains durable evidence before a fresh attempt.
 - When a validated hop changes a lockfile, inspect the resolved dependency delta and license findings, then durably record both with `record-dependency-review --report <report-path> --compatibility <finding> --licenses <finding>` before requesting the checkpoint. Never bypass this gate merely because tests pass.
-- Never create, switch, delete, merge, push, fetch, reconfigure, or directly commit Git branches/remotes. Never invoke GitHub CLI, publishing, release, deployment, credential, or destructive database commands. The only permitted commit paths are Ruby-only `opencode-ruby-upgrader commit-hop --report <report-path>` and Rails-bridge-only `opencode-ruby-upgrader commit-rails-hop --report <report-path>` after their respective validation gates succeed.
+- Never create, switch, delete, merge, push, fetch, reconfigure, or directly commit Git branches/remotes. Never invoke GitHub CLI, publishing, release, deployment, credential, or destructive database commands. The only permitted commit paths are Ruby-only `opencode-ruby-upgrader commit-hop --report <report-path>`, Rails-bridge-only `opencode-ruby-upgrader commit-rails-hop --report <report-path>`, and Bundler-bridge-only `opencode-ruby-upgrader commit-bundler-hop --report <report-path>` after their respective validation gates succeed.
 - Before every edit, acknowledge: this is automated migration assistance; the user must review diffs, tests, and any deployment. Never claim production safety.
-- Require a clean working tree before the first iteration, excluding only the plugin-owned `.ruby-upgrades` evidence directory. Do not ask the user to review or clean evidence files that this run just created; inspect and stop for every other tracked, staged, or untracked project change. Record branch, starting SHA, runtime/OS, Bundler, test commands, the pinned target Ruby version, source URLs, and source access date in `.ruby-upgrades/runs/<timestamp>.json` and an adjacent Markdown report. These files are versioned migration evidence. `begin` already acquires the single-worktree lock. Use `resume` only after a paused or interrupted run; `complete`, `blocked`, and `paused` runs release their lock. A Ruby run blocked by an approved Rails bridge must not resume.
+- Require a clean working tree before the first iteration, excluding only the plugin-owned `.ruby-upgrades` evidence directory. Do not ask the user to review or clean evidence files that this run just created; inspect and stop for every other tracked, staged, or untracked project change. Record branch, starting SHA, runtime/OS, Bundler, test commands, the pinned target Ruby version, source URLs, and source access date in `.ruby-upgrades/runs/<timestamp>.json` and an adjacent Markdown report. These files are versioned migration evidence. `begin` already acquires the single-worktree lock. Use `resume` only after a paused or interrupted run; `complete`, `blocked`, and `paused` runs release their lock. A Ruby run blocked by an approved Rails or Bundler bridge must not resume.
 - Never ask a user to provide or restore an internal report path, run ID, container name, or runtime manifest. If no resumable durable run exists, explain that the prior local run evidence is unavailable and direct the user to restart with `/ruby-upgrade --target <version>`; retain the same safety gates and plainly summarize the new plan before any side effect. When stale paused reports exist, retain them as evidence but select the most recently started paused report matching the current branch and requested target; use that report path internally for resume and target-runtime preparation.
+- Each generated report and dashboard card includes an advisory infrastructure review of the reader's own files: stale Ruby pins, CI workflows that do not yet test the target, and the recorded `BUNDLED WITH` Bundler pin. It is read-only and never blocks or gates a hop. Present these findings when the run completes, do not act on them automatically, and do not treat an intentional version pin that lags the app as a defect.
 - A successful routine iteration is proposed locally through the commit gate and requires an OpenCode confirmation. The gate requires the original linked worktree/branch, an unchanged expected HEAD, a completed report iteration with passing tests, an empty initial staging area, and no detected credential material. The user alone reviews, pushes, and deploys; they may push any validated local checkpoint.
 - Stop rather than guess on data migrations, authentication/authorization, payments, serialization, background jobs, native extensions, secrets, production configuration, required framework-major upgrades, private dependency sources, or failed validation. Explain the evidence and offer safe continuation options.
 

package/bin/opencode-ruby-upgrader.mjs

@@ -3,7 +3,7 @@ import { inspectGitCapabilities, inspectWorktree, setupInstructions } from "../s
 import { startDashboard } from "../src/dashboard.js";
 import { commitValidatedHop, commitValidatedRailsHop, CommitGateError } from "../src/commit-hop.js";
 import { acquireRunLock, readRun, releaseRunLock, RunStateError } from "../src/run-state.js";
-import { beginRailsBridgeRun, beginRun, discardLastRailsIteration, discardPendingRailsAppUpdate, recordDependencyReview, recordExecutedIteration, recordExecutedRailsIteration, recordFrameworkBridge, recordRailsResearch, recordResearch, recordRiskDecision, resumeRun, runStatus, transitionRun } from "../src/controller.js";
+import { beginBundlerBridgeRun, beginRailsBridgeRun, beginRun, discardLastRailsIteration, discardPendingRailsAppUpdate, recordBundlerBridge, recordBundlerResearch, recordDependencyReview, recordExecutedBundlerIteration, recordExecutedIteration, recordExecutedRailsIteration, recordFrameworkBridge, recordRailsResearch, recordResearch, recordRiskDecision, resumeRun, runStatus, transitionRun } from "../src/controller.js";
 import { inventoryProject } from "../src/inventory.js";
 import { inspectSupplyChain } from "../src/supply-chain.js";
 import { prepareTargetRuntime } from "../src/target-runtime.js";
@@ -13,7 +13,7 @@ const option = (name) => { const index = args.indexOf(name); return index >= 0 ?
 const options = (name) => args.flatMap((argument, index) => argument === name && args[index + 1] ? [args[index + 1]] : []);
 const reportOption = () => option("--report");
 const citation = (value) => { const [title, url] = (value ?? "").split("|"); return { title, url }; };
-const usage = "Usage: opencode-ruby-upgrader <preflight|dashboard|begin|begin-rails-bridge|prepare-target-runtime|status|transition|record-research|record-rails-research|record-risk|record-framework-bridge|record-executed-iteration|record-executed-rails-iteration|discard-pending-app-update|discard-last-rails-iteration|record-dependency-review|inventory|supply-chain|git-capabilities|commit-hop|commit-rails-hop|resume|release-lock> [--help]";
+const usage = "Usage: opencode-ruby-upgrader <preflight|dashboard|begin|begin-rails-bridge|begin-bundler-bridge|prepare-target-runtime|status|transition|record-research|record-rails-research|record-bundler-research|record-risk|record-framework-bridge|record-bundler-bridge|record-executed-iteration|record-executed-rails-iteration|record-executed-bundler-iteration|discard-pending-app-update|discard-last-rails-iteration|record-dependency-review|inventory|supply-chain|git-capabilities|commit-hop|commit-rails-hop|commit-bundler-hop|resume|release-lock> [--help]";
 const prepareRuntimeHelp = `Usage: opencode-ruby-upgrader prepare-target-runtime --ruby <x.y.z> [--database postgres|mysql] [--report .ruby-upgrades/runs/<run>.json]
 
 Prepares an isolated, run-bound Docker runtime. The database is detected from mysql2/PostgreSQL project declarations; absent evidence defaults to PostgreSQL, while conflicting evidence requires --database. Use --database only to override detection deliberately.`;
@@ -38,6 +38,9 @@ if (command === "prepare-target-runtime" && args.includes("--help")) {
 } else if (command === "begin-rails-bridge") {
   try { console.log(JSON.stringify(beginRailsBridgeRun({ rubyReportPath: option("--ruby-report"), dryRun: args.includes("--dry-run"), stopAfterHop: args.includes("--stop-after-hop") }), null, 2)); }
   catch (error) { console.error(`Rails bridge start blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "begin-bundler-bridge") {
+  try { console.log(JSON.stringify(beginBundlerBridgeRun({ rubyReportPath: option("--ruby-report"), dryRun: args.includes("--dry-run"), stopAfterHop: args.includes("--stop-after-hop") }), null, 2)); }
+  catch (error) { console.error(`Bundler bridge start blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "prepare-target-runtime") {
   try {
     if (!option("--ruby")) throw new Error("Usage: prepare-target-runtime --ruby <x.y.z> [--database postgres|mysql] [--report .ruby-upgrades/runs/<run>.json]");
@@ -62,18 +65,27 @@ if (command === "prepare-target-runtime" && args.includes("--help")) {
 } else if (command === "record-rails-research") {
   try { console.log(JSON.stringify(recordRailsResearch({ reportPath: reportOption(), ladder: (option("--ladder") ?? "").split(",").filter(Boolean), citations: options("--citation").map(citation) }), null, 2)); }
   catch (error) { console.error(`Rails research recording blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-bundler-research") {
+  try { console.log(JSON.stringify(recordBundlerResearch({ reportPath: reportOption(), ladder: option("--ladder")?.split(","), citations: options("--citation").map(citation) }), null, 2)); }
+  catch (error) { console.error(`Bundler research blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "record-risk") {
   try { console.log(JSON.stringify(recordRiskDecision({ reportPath: reportOption(), risk: option("--risk"), decision: option("--decision"), evidence: option("--evidence") }), null, 2)); }
   catch (error) { console.error(`Risk recording blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "record-framework-bridge") {
   try { console.log(JSON.stringify(recordFrameworkBridge({ reportPath: reportOption(), rubyFrom: option("--ruby-from"), rubyTo: option("--ruby-to"), railsFrom: option("--rails-from"), railsTo: option("--rails-to"), rationale: option("--rationale"), citations: options("--citation").map(citation) }), null, 2)); }
   catch (error) { console.error(`Rails compatibility bridge blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-bundler-bridge") {
+  try { console.log(JSON.stringify(recordBundlerBridge({ reportPath: reportOption(), rubyFrom: option("--ruby-from"), rubyTo: option("--ruby-to"), bundlerFrom: option("--bundler-from"), bundlerTo: option("--bundler-to"), minimumBundler: option("--minimum-bundler"), rationale: option("--rationale"), citations: options("--citation").map(citation) }), null, 2)); }
+  catch (error) { console.error(`Bundler compatibility bridge blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "record-executed-iteration") {
   try { console.log(JSON.stringify(recordExecutedIteration({ reportPath: reportOption(), iteration: JSON.parse(option("--json") ?? ""), validationCommandId: option("--validation") }), null, 2)); }
   catch (error) { console.error(`Executed validation blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "record-executed-rails-iteration") {
   try { console.log(JSON.stringify(recordExecutedRailsIteration({ reportPath: reportOption(), iteration: JSON.parse(option("--json") ?? ""), testValidationCommandId: option("--validation") }), null, 2)); }
   catch (error) { console.error(`Executed Rails validation blocked: ${error.message}`); process.exitCode = 1; }
+} else if (command === "record-executed-bundler-iteration") {
+  try { console.log(JSON.stringify(recordExecutedBundlerIteration({ reportPath: reportOption(), iteration: JSON.parse(option("--iteration") ?? "{}"), validationCommandId: option("--validation-command-id") }), null, 2)); }
+  catch (error) { console.error(`Bundler hop blocked: ${error.message}`); process.exitCode = 1; }
 } else if (command === "discard-pending-app-update") {
   try { console.log(JSON.stringify(discardPendingRailsAppUpdate({ reportPath: reportOption(), reason: option("--reason") }), null, 2)); }
   catch (error) { console.error(`Rails app:update discard blocked: ${error.message}`); process.exitCode = 1; }
@@ -103,6 +115,10 @@ if (command === "prepare-target-runtime" && args.includes("--help")) {
   const reportIndex = args.indexOf("--report");
   try { console.log(JSON.stringify(commitValidatedRailsHop({ reportPath: reportIndex >= 0 ? args[reportIndex + 1] : undefined, allowHooks: args.includes("--allow-hooks"), allowBroadLockfile: args.includes("--allow-broad-lockfile"), allowPrivateSources: args.includes("--allow-private-sources") }), null, 2)); }
   catch (error) { console.error(`${error instanceof CommitGateError ? `Rails commit blocked (${error.code})` : "Rails commit failed"}: ${error.message}`); process.exitCode = 1; }
+} else if (command === "commit-bundler-hop") {
+  const reportIndex = args.indexOf("--report");
+  try { console.log(JSON.stringify(commitValidatedBundlerHop({ reportPath: reportIndex >= 0 ? args[reportIndex + 1] : undefined, allowHooks: args.includes("--allow-hooks"), allowBroadLockfile: args.includes("--allow-broad-lockfile"), allowPrivateSources: args.includes("--allow-private-sources") }), null, 2)); }
+  catch (error) { console.error(`${error instanceof CommitGateError ? `Bundler commit blocked (${error.code})` : "Bundler commit failed"}: ${error.message}`); process.exitCode = 1; }
 } else if (["resume", "release-lock"].includes(command)) {
   const reportIndex = args.indexOf("--report");
   const reportPath = reportIndex >= 0 ? args[reportIndex + 1] : undefined;

package/docs/bundler-bridge.md

@@ -0,0 +1,107 @@
+# Bundler bridge lifecycle
+
+A Bundler bridge is the mirror image of a [Rails bridge](rails-bridge.md). Where a Rails hop is blocked because the framework lags the Ruby, a Bundler hop is blocked because the project's own pinned Bundler lags the Ruby it must now run on.
+
+## Why this exists
+
+`Gemfile.lock` records the Bundler that wrote it under `BUNDLED WITH`, and Bundler switches to that version automatically. It is therefore the most reliable available signal for which Bundler will actually run in your project — more reliable than scanning for an installed gem.
+
+The official compatibility guide at <https://guides.rubygems.org/bundler-compatibility/> is a table of **minimum floors**, not fixed pairings:
+
+| Bundler | Requires Ruby | Requires RubyGems |
+| --- | --- | --- |
+| 4.0 | >= 3.2.0 | >= 3.4.1 |
+| 2.7 | >= 3.2.0 | >= 3.4.1 |
+| 2.6 | >= 3.1.0 | >= 3.3.3 |
+| 2.5 | >= 3.0.0 | >= 3.2.3 |
+
+A higher Bundler supports a *wider* range of Rubies, so moving Ruby forward essentially never forces a Bundler upgrade. Each Ruby release simply ships a matching pair as its default. The compatibility risk runs the other way: an **existing Bundler pin breaks when the Ruby moves forward**.
+
+Two corrections worth stating plainly, because the intuitive version of this is wrong:
+
+- "Ruby 4 requires Bundler 4" is not a constraint. Bundler 2.7 and 4.0 both support Ruby >= 3.2.
+- Ruby 4.0 ships Bundler 4.0 as its bundled default. That is a convenience pairing, not a compatibility requirement.
+
+## No hardcoded table
+
+`src/bundler-compat.js` deliberately stores no versions. This tool performs no network requests, so it cannot look up which Bundler supports which Ruby, and a baked-in table would silently rot at the next series release.
+
+The minimum floor arrives the same way Rails and Ruby compatibility facts already enter this system: supplied as cited research at the moment the bridge is approved, and recorded in the run report so it can be re-verified later. Only the comparison arithmetic — version ordering, contiguity, floor checks — lives locally, because that has to be deterministic for an approval to be defensible.
+
+## Lifecycle
+
+### 1. Approve the bridge on the blocked Ruby run
+
+```bash
+opencode-ruby-upgrader record-bundler-bridge --report <run>.json \
+  --ruby-from 3.3 --ruby-to 3.4 \
+  --bundler-from 2.4.17 --bundler-to 2.5.22 \
+  --minimum-bundler 2.5 \
+  --rationale "Bundler 2.4 predates Ruby 3.4 support." \
+  --citation "Bundler compatibility with Ruby|https://guides.rubygems.org/bundler-compatibility/"
+
+opencode-ruby-upgrader transition --report <run>.json --phase blocked
+```
+
+The bridge records the floor, the rationale, the citation, and the compatibility source URL. The Ruby run becomes **terminal**: it cannot be resumed, because resuming would skip the prerequisite change and leave the project on a Bundler that cannot run the target Ruby.
+
+Approval is refused when the recorded pin already clears the floor. Blocking a hop that the pin already satisfies would be wrong as often as it is right.
+
+### 2. Begin the separate bridge run
+
+```bash
+opencode-ruby-upgrader begin-bundler-bridge --ruby-report <blocked-ruby-report>.json
+```
+
+This creates a `reportType: "bundler_bridge"` report linked back to the blocked Ruby run through `bridge.rubyReportPath` and `bridge.rubyRunId`.
+
+### 3. Research a contiguous ladder
+
+```bash
+opencode-ruby-upgrader record-bundler-research --report <bridge>.json \
+  --ladder 2.4.17,2.5.22,2.6.9,2.7.2,4.0.11 \
+  --citation "Bundler compatibility with Ruby|https://guides.rubygems.org/bundler-compatibility/"
+```
+
+The ladder must begin at the recorded `BUNDLED WITH` pin and advance one series at a time. A direct **2.7 → 4.0** hop is valid because Bundler never had a 3.x series; without that boundary rule a project on 2.4 could never reach 4.0 through a reviewed ladder.
+
+### 4. Raise the pin and validate
+
+Rewrite the pin inside the isolated runtime, then record the hop:
+
+```bash
+opencode-ruby-upgrader record-executed-bundler-iteration --report <bridge>.json \
+  --iteration '<json>' --validation-command-id docker-bundle-rspec
+```
+
+This is where a Bundler bridge differs from a Rails bridge. A Rails hop produces a reviewable `app:update` receipt; a Bundler hop produces a **file change**, and a lockfile edit is weak evidence — anyone can hand-write `BUNDLED WITH 2.5.22`.
+
+So the hop is accepted only when **two independent facts agree**:
+
+1. The rewritten `BUNDLED WITH` pin in `Gemfile.lock` matches the hop target.
+2. The Bundler version that actually executed the tests matches the hop target, attested by the isolated runtime.
+
+A mismatch is refused explicitly, for example: `Validation executed Bundler 2.4.22, not 2.5.22. Re-prepare the target runtime on the new Bundler before recording this hop.`
+
+The recorded pin is stored on the iteration as `lockfilePin`, and report validation rejects any hop whose pin disagrees with its target.
+
+### 5. Checkpoint
+
+```bash
+opencode-ruby-upgrader transition --report <bridge>.json --phase hop_validated
+opencode-ruby-upgrader commit-bundler-hop --report <bridge>.json
+```
+
+The checkpoint message carries `Bundler-Upgrade-Report`, `Bundler-Upgrade-Hop`, and `Bundler-Bridge-Ruby-Report` trailers, so the linkage back to the blocked Ruby run survives in Git history and can be verified later.
+
+### 6. Restart the Ruby upgrade
+
+Only after the bridge is complete should a fresh Ruby run begin.
+
+## Rollback
+
+Use the reviewable local history: `git revert <hop-sha>`. Do not use reset, rebase, or force-push as routine migration recovery.
+
+## Reporting to the user
+
+Advisory findings about the `BUNDLED WITH` pin appear in every report's **Infrastructure review (advisory)** section and on the dashboard. They are read-only and never gate a hop: an intentional version pin that lags the app is legitimate in many repositories. Where a value cannot be read with confidence, the tool stays silent rather than guessing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ruby-upgrader",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "A safe, evidence-driven Ruby runtime upgrade agent and local migration dashboard for OpenCode",
   "author": "Priscilla Cournoyer (https://github.com/lilla021)",
   "repository": {
@@ -26,9 +26,35 @@
   "allowScripts": {
     "opencode-ai@1.18.30": true
   },
-  "files": ["src", "agents", "bin", "docs/*.md", "README.md", "LICENSE", "SECURITY.md", "PRIVACY.md", "RELEASING.md", "RELEASE_CHECKLIST.md", "RELEASE_NOTES.md", "E2E_EVIDENCE.md"],
-  "keywords": ["opencode", "opencode-plugin", "ruby", "rails", "upgrade", "worktree", "migration"],
-  "engines": { "node": ">=22.5.0" },
+  "files": [
+    "src",
+    "agents",
+    "bin",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "PRIVACY.md",
+    "RELEASING.md",
+    "RELEASE_CHECKLIST.md",
+    "RELEASE_NOTES.md",
+    "E2E_EVIDENCE.md",
+    "docs/bundler-bridge.md",
+    "docs/rails-bridge.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ruby",
+    "rails",
+    "upgrade",
+    "worktree",
+    "migration"
+  ],
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "license": "MIT",
-  "publishConfig": { "access": "public" }
-}
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/advisory.js

@@ -0,0 +1,140 @@
+// Read-only advisory findings about infrastructure the upgrade may have made
+// inconsistent.
+//
+// Everything here is advisory by design and never blocks a commit. The agent
+// runs the app in an isolated container; it does not have your CI config, your
+// deploy host, or your platform's build process. A finding says "this file
+// disagrees with the version you just moved to, confirm it" -- never "you must
+// change this". A deliberate version pin that lags the app is legitimate in many
+// repos, and blocking on it would be wrong as often as right.
+//
+// Each finding carries the evidence it was derived from so the reader can judge
+// it. `confidence` distinguishes a value read out of a file ("observed") from a
+// judgment about what that value implies ("review").
+
+import fs from "node:fs";
+import path from "node:path";
+
+const exists = (root, file) => fs.existsSync(path.join(root, file));
+const read = (root, file) => (exists(root, file) ? fs.readFileSync(path.join(root, file), "utf8") : "");
+
+function finding(severity, area, title, detail, evidence, confidence = "observed") {
+  return { severity, area, title, detail, evidence, confidence };
+}
+
+// `BUNDLED WITH` is the project's own record of which Bundler wrote its
+// lockfile, and Bundler auto-switches to it. That makes it the most reliable
+// available signal for "which Bundler will actually run here" -- more reliable
+// than scanning for an installed gem, and the value a Ruby hop can invalidate.
+export function bundledWith(root = process.cwd()) {
+  const lockfile = read(root, "Gemfile.lock");
+  const match = /^BUNDLED WITH\s*\r?\n\s+(\d+(?:\.\d+)+)/m.exec(lockfile);
+  return match?.[1] ?? null;
+}
+
+// Ruby version declarations, read from the files that actually pin one. Values
+// are reported verbatim: an odd but intentional pin is still worth showing.
+export function rubyPins(root = process.cwd()) {
+  const pins = [];
+  const versionFiles = [".ruby-version", ".tool-versions", ".mise.toml"];
+  for (const file of versionFiles) {
+    if (!exists(root, file)) continue;
+    const contents = read(root, file);
+    const value = contents.match(/^\s*(\d+\.\d+(?:\.\d+)?)\s*$/m)?.[1]
+      ?? contents.match(/^\s*ruby\s+(\d+\.\d+(?:\.\d+)?)\s*$/m)?.[1]
+      ?? contents.match(/ruby\s*=\s*["'](\d+\.\d+(?:\.\d+)?)/)?.[1]
+      ?? null;
+    if (value) pins.push({ file, value });
+  }
+  if (exists(root, "Dockerfile")) {
+    const match = read(root, "Dockerfile").match(/^\s*FROM\s+ruby:(\d+\.\d+(?:\.\d+)?)/im);
+    if (match) pins.push({ file: "Dockerfile", value: match[1] });
+  }
+  if (exists(root, "Gemfile")) {
+    const match = read(root, "Gemfile").match(/^\s*ruby\s+["']([\d.]+)["']/m);
+    if (match) pins.push({ file: "Gemfile", value: match[1] });
+  }
+  return pins;
+}
+
+// CI workflows are inspected conservatively. YAML matrix shapes vary far too
+// much to parse reliably, so this only reports Ruby versions it can see as plain
+// scalars and stays silent otherwise. Reporting nothing is better than guessing
+// at a matrix it only partly understood.
+export function ciRubyVersions(root = process.cwd()) {
+  const found = [];
+  const workflows = exists(root, ".github/workflows")
+    ? fs.readdirSync(path.join(root, ".github/workflows")).filter((f) => /\.ya?ml$/.test(f))
+    : [];
+  for (const file of workflows) {
+    const contents = read(root, path.join(".github/workflows", file));
+    const seen = new Set();
+    for (const match of contents.matchAll(/(?:ruby[-_]?version|ruby|RUBY_VERSION)["'\s:=]+(\d+\.\d+(?:\.\d+)?)/gi)) {
+      seen.add(match[1]);
+    }
+    if (seen.size) found.push({ file: path.join(".github/workflows", file), versions: [...seen].sort() });
+  }
+  return found;
+}
+
+const series = (version) => (version ?? "").split(".").slice(0, 2).join(".");
+const sameSeries = (a, b) => series(a) === series(b) && series(a) !== "";
+
+// `advisoryFindings` is intentionally read-only and dependency-free so it can be
+// called from report writing without pulling in the Docker runtime machinery.
+export function advisoryFindings({ root = process.cwd(), run = {}, inventory = {} } = {}) {
+  const findings = [];
+  const target = run.targetRuby;
+  const targetSeries = series(target);
+  const pins = rubyPins(root);
+  const ciVersions = ciRubyVersions(root);
+  const bundler = bundledWith(root);
+
+  for (const pin of pins) {
+    if (!target || sameSeries(pin.value, target)) continue;
+    findings.push(finding(
+      "review",
+      "version-pin",
+      `${pin.file} pins Ruby ${pin.value}, but this run targeted ${target}`,
+      `Update this if the deploy platform reads it, or leave it if it intentionally lags the app. Confirm which one your production runtime actually honours.`,
+      `${pin.file}: ${pin.value}`
+    ));
+  }
+
+  const pinFiles = new Set(pins.map((p) => p.file));
+  if (!pinFiles.has("Dockerfile") && exists(root, "Dockerfile")) {
+    findings.push(finding("review", "version-pin", "Dockerfile has no parseable Ruby base image", "The base image tag could not be read, so its Ruby version was not compared against this run.", "Dockerfile: unparsed", "review"));
+  }
+
+  for (const workflow of ciVersions) {
+    const behind = workflow.versions.filter((version) => targetSeries && series(version) < targetSeries);
+    if (!behind.length) continue;
+    findings.push(finding(
+      "review",
+      "ci",
+      `${workflow.file} does not test Ruby ${target}`,
+      `It references ${behind.join(", ")}. If CI keeps testing the older version, a regression on the new one would not be caught before merge.`,
+      `${workflow.file}: ${workflow.versions.join(", ")}`
+    ));
+  }
+
+  if (bundler && target) {
+    findings.push(finding(
+      "review",
+      "bundler",
+      `Gemfile.lock pins Bundler ${bundler}`,
+      `This run validated the app inside a container. Bundler switches to the version in \`BUNDLED WITH\`, so confirm your deploy host and CI resolve ${bundler} and that it supports Ruby ${target}. If it does not, the hop needs a Bundler upgrade scoped as its own run.`,
+      `Gemfile.lock BUNDLED WITH: ${bundler}`
+    ));
+  }
+
+  if (inventory.deploy?.length && !exists(root, ".ruby-version") && !exists(root, "Dockerfile")) {
+    findings.push(finding("review", "platform", "No shared Ruby version file", `Deploy files exist (${inventory.deploy.join(", ")}) but there is no \`.ruby-version\`, \`.tool-versions\`, \`.mise.toml\`, or \`Dockerfile\`. The Ruby version may then be defined only inside a platform dashboard or base image you cannot see from here.`, `deploy: ${inventory.deploy.join(", ")}`));
+  }
+
+  if (exists(root, "Gemfile.lock") && !fs.statSync(path.join(root, "Gemfile.lock")).isFile()) {
+    findings.push(finding("review", "lockfile", "Gemfile.lock is not a regular file", "Its BUNDLED WITH value was not read, so no Bundler finding is reported.", "Gemfile.lock", "review"));
+  }
+
+  return findings;
+}

package/src/bundler-compat.js

@@ -0,0 +1,68 @@
+// Bundler/Ruby compatibility facts for the Bundler bridge.
+//
+// This module deliberately holds no version table. The tool performs no network
+// requests, so it cannot look up which Bundler supports which Ruby, and a
+// hardcoded table would silently rot the first time RubyGems cut a series.
+// Instead the *floor* is supplied by the agent as cited research at the moment a
+// bridge is approved -- the same way Rails and Ruby compatibility facts already
+// enter this system -- and recorded in run evidence so it can be re-verified.
+//
+// What lives here is the arithmetic: comparing versions, and deciding whether a
+// declared floor is genuinely above the project's pin. That logic must be local
+// and deterministic, because it is what makes an approval defensible.
+
+export const BUNDLER_COMPATIBILITY_SOURCE = "https://guides.rubygems.org/bundler-compatibility/";
+
+// The official guide is a table of *minimum floors*, not fixed pairings: Bundler
+// 2.5 requires Ruby >= 3.0, 2.6 requires >= 3.1, and 2.7 and 4.0 both require
+// >= 3.2. A higher Bundler supports a wider range of Rubies, so a Ruby hop
+// forward essentially never forces a Bundler upgrade -- an *existing* Bundler
+// pin is what breaks when the Ruby moves. The bridge therefore exists because
+// this project's pin lags its new Ruby, which is the mirror image of the Rails
+// bridge (where Rails lagging Ruby blocks the hop).
+export const bundlerVersion = /^\d+\.\d+(?:\.\d+)?$/;
+
+export const bundlerSeries = (value) => String(value ?? "").split(".").slice(0, 2).join(".");
+const parts = (value) => bundlerSeries(value).split(".").map(Number);
+export const compareBundler = (left, right) => {
+  const [lMajor, lMinor] = parts(left); const [rMajor, rMinor] = parts(right);
+  return lMajor !== rMajor ? lMajor - rMajor : lMinor - rMinor;
+};
+
+// Bundler series move +1 per minor, with one major boundary: the 2.x line ends
+// at 2.7 and the next series is 4.0. That jump is major 2 to 4 -- major 3 was
+// never a Bundler series -- so this is an explicit successor rather than the
+// +1 pattern Ruby uses. Treating 2.7 -> 4.0 as a valid single hop is required
+// because that is how the official series run; without it a project on 2.4 could
+// never reach 4.0 through a reviewed ladder.
+const bundlerSeriesSuccessors = new Map([["2.7", "4.0"]]);
+export const contiguousBundlerHop = (from, to) => {
+  const [fromMajor, fromMinor] = parts(from); const [toMajor, toMinor] = parts(to);
+  if (![fromMajor, fromMinor, toMajor, toMinor].every((value) => Number.isInteger(value))) return false;
+  return toMajor === fromMajor && toMinor === fromMinor + 1
+    || bundlerSeriesSuccessors.get(bundlerSeries(from)) === bundlerSeries(to);
+};
+
+// True when the project's recorded `BUNDLED WITH` pin sits below a researched
+// floor. Bundler auto-switches to that pin, so this is the version that will
+// actually run -- and the reason a hop is blocked.
+export function bundlerPinBelowFloor({ pinned, minimum }) {
+  if (!bundlerVersion.test(String(pinned ?? "")) || !bundlerVersion.test(String(minimum ?? ""))) return false;
+  return compareBundler(pinned, minimum) < 0;
+}
+
+// A ladder must start at the pin and reach the researched floor one contiguous
+// minor series at a time, so no hop can skip an intermediate Bundler whose
+// behavior changes are themselves unreviewed.
+export function validateBundlerLadder({ ladder, pinned, target }) {
+  if (!Array.isArray(ladder) || ladder.length < 2) return "A Bundler research ladder must contain at least two versions.";
+  if (ladder.some((version) => !bundlerVersion.test(version))) return "A Bundler research ladder must contain Bundler versions.";
+  if (bundlerSeries(ladder[0]) !== bundlerSeries(pinned)) return "A Bundler research ladder must begin at the version recorded in BUNDLED WITH.";
+  // Contiguity is checked before the endpoint so a ladder that both skips a
+  // series and overshoots reports the more specific problem.
+  for (let index = 1; index < ladder.length; index += 1) {
+    if (!contiguousBundlerHop(ladder[index - 1], ladder[index])) return "A Bundler research ladder must advance one minor series per hop, or across the 2.7 to 4.0 series boundary.";
+  }
+  if (bundlerSeries(ladder.at(-1)) !== bundlerSeries(target)) return "A Bundler research ladder must end at the researched target Bundler.";
+  return null;
+}

package/src/commit-hop.js

@@ -34,11 +34,12 @@ function readReport(root, reportPath) {
   catch { throw new CommitGateError("The upgrade report is missing or fails the run schema.", "invalid-report"); }
 }
 
-function assertValidatedIteration(report, rails = false) {
+function assertValidatedIteration(report, bridge = null) {
   const iteration = report.iterations?.at(-1);
-  if (rails ? (!report.targetRails || !report.targetRailsPinnedAt || !report.bridge) : (!report.targetRuby || !report.targetPinnedAt)) {
-    throw new CommitGateError("The report must pin its target and bridge evidence before an automatic commit.", "target-not-pinned");
-  }
+  const pinned = bridge === "rails" ? (report.targetRails && report.targetRailsPinnedAt && report.bridge)
+    : bridge === "bundler" ? (report.targetBundler && report.targetBundlerPinnedAt && report.bridge)
+      : (report.targetRuby && report.targetPinnedAt);
+  if (!pinned) throw new CommitGateError("The report must pin its target and bridge evidence before an automatic commit.", "target-not-pinned");
   if (!iteration || iteration.status !== "complete" || iteration.tests?.passed !== true) {
     throw new CommitGateError("The latest hop is not recorded as complete with passing tests.", "validation-missing");
   }
@@ -52,7 +53,11 @@ function assertValidatedIteration(report, rails = false) {
   if (!Array.isArray(iteration.fixes) || !iteration.fixes.length || !Array.isArray(iteration.citations) || !iteration.citations.length || !iteration.tests?.smoke) {
     throw new CommitGateError("The latest hop requires explained fixes, citations, and smoke-test evidence.", "evidence-missing");
   }
-  if (rails && !iteration.appUpdateReview) throw new CommitGateError("The latest Rails hop requires reviewed bin/rails app:update evidence.", "app-update-review-missing");
+  if (bridge === "rails" && !iteration.appUpdateReview) throw new CommitGateError("The latest Rails hop requires reviewed bin/rails app:update evidence.", "app-update-review-missing");
+  // A Bundler hop changes the lockfile, so the commit must carry the pin it
+  // produced. Committing a hop whose recorded pin disagrees with its target
+  // would publish evidence that does not match the repository state.
+  if (bridge === "bundler" && (!iteration.lockfilePin || iteration.lockfilePin.split(".").slice(0, 2).join(".") !== iteration.to.split(".").slice(0, 2).join("."))) throw new CommitGateError("The latest Bundler hop must record the BUNDLED WITH pin it produced.", "bundler-pin-missing");
   return iteration;
 }
 
@@ -161,9 +166,13 @@ function assertValidationFingerprint(cwd, iteration) {
   }
 }
 
-function messageFor(iteration, reportPath, report, rails = false) {
+function messageFor(iteration, reportPath, report, bridge = null) {
   const receiptTrailer = iteration.validationReceipts?.length ? [`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`] : [];
-  if (rails) return [
+  if (bridge === "bundler") return [
+    `chore(bundler): upgrade ${iteration.from} to ${iteration.to}`, "", "Raise the BUNDLED WITH floor recorded in Gemfile.lock so this project can run on the target Ruby.", `Validation: ${iteration.tests.command || "project test suite"} executed on Bundler ${iteration.lockfilePin}.`, `Evidence: ${reportPath}`,
+    `Bundler-Upgrade-Report: ${reportPath}`, `Bundler-Upgrade-Hop: ${iteration.from}->${iteration.to}`, `Bundler-Bridge-Ruby-Report: ${report.bridge.rubyReportPath}`, ...receiptTrailer
+  ].join("\n");
+  if (bridge === "rails") return [
     `chore(rails): upgrade ${iteration.from} to ${iteration.to}`, "", "Apply the reviewed Rails framework compatibility changes.", `Validation: ${iteration.tests.command || "project test suite"}.`, `Evidence: ${reportPath}`,
     `Rails-Upgrade-Report: ${reportPath}`, `Rails-Upgrade-Hop: ${iteration.from}->${iteration.to}`, `Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`, `Rails-Bridge-Ruby-Report: ${report.bridge.rubyReportPath}`, ...receiptTrailer
   ].join("\n");
@@ -178,7 +187,7 @@ function messageFor(iteration, reportPath, report, rails = false) {
   ].join("\n");
 }
 
-function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false, allowBroadLockfile = false, allowPrivateSources = false, rails = false }) {
+function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false, allowBroadLockfile = false, allowPrivateSources = false, bridge = null }) {
   if (!reportPath) throw new CommitGateError("Provide --report .ruby-upgrades/runs/<run>.json.", "missing-report-path");
   const state = gitState(cwd);
   if (!state.linked || !state.branch || !state.defaultBranch || state.branch === state.defaultBranch) {
@@ -191,8 +200,9 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
   if (!report.lockNonce) throw new CommitGateError("The report is missing its active lock capability.", "lock-capability-missing");
   try { assertRunLock(state.root, reportPath, report.lockNonce); }
   catch (error) { throw new CommitGateError(error.message, error.code); }
-  const iteration = assertValidatedIteration(report, rails);
-  if (report.schemaVersion !== 2 || report.phase !== "hop_validated" || Boolean(report.reportType === "rails_bridge") !== rails) throw new CommitGateError("The run must use the current schema and transition to hop_validated before an automatic commit.", "phase-not-validated");
+  const iteration = assertValidatedIteration(report, bridge);
+  const expectedType = bridge === "rails" ? "rails_bridge" : bridge === "bundler" ? "bundler_bridge" : "ruby";
+  if (report.schemaVersion !== 2 || report.phase !== "hop_validated" || (report.reportType ?? "ruby") !== expectedType) throw new CommitGateError("The run must use the current schema and transition to hop_validated before an automatic commit.", "phase-not-validated");
   if (report.branch !== state.branch) throw new CommitGateError("The worktree branch no longer matches the recorded run branch.", "unexpected-branch");
   assertExpectedHead(state, report);
   const indexPath = path.resolve(cwd, text(cwd, ["rev-parse", "--git-path", "index"]));
@@ -216,7 +226,7 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
     throw new CommitGateError(`Potential credential material detected in: ${secretPaths.join(", ")}. Review it manually; it was not committed.`, "secret-detected");
   }
 
-  const message = messageFor(iteration, relativeReport, report, rails);
+  const message = messageFor(iteration, relativeReport, report, bridge);
     assertValidationFingerprint(cwd, iteration);
     if (text(cwd, ["rev-parse", "HEAD"]) !== report.expectedHead) throw new CommitGateError("HEAD changed while the commit gate was validating; refusing to commit atop unexpected history.", "unexpected-head");
     commit(cwd, message, env);
@@ -230,5 +240,6 @@ function commitValidated({ cwd = process.cwd(), reportPath, allowHooks = false,
   }
 }
 
-export function commitValidatedHop(options = {}) { return commitValidated(options); }
-export function commitValidatedRailsHop(options = {}) { return commitValidated({ ...options, rails: true }); }
+export function commitValidatedHop(options = {}) { return commitValidated({ ...options, bridge: null }); }
+export function commitValidatedRailsHop(options = {}) { return commitValidated({ ...options, bridge: "rails" }); }
+export function commitValidatedBundlerHop(options = {}) { return commitValidated({ ...options, bridge: "bundler" }); }

package/src/controller.js

@@ -4,9 +4,11 @@ import { execFileSync } from "node:child_process";
 import { inspectGitCapabilities, inspectWorktree } from "./preflight.js";
 import { inventoryProject } from "./inventory.js";
 import { inspectSupplyChain } from "./supply-chain.js";
+import { bundledWith as inventoryBundledWith } from "./advisory.js";
 import { acquireRunLock, assertRunLock, readRun, releaseRunLock, writeRun } from "./run-state.js";
 import { executeValidation } from "./validation-executor.js";
 import { receiptDigest } from "./provenance.js";
+import { BUNDLER_COMPATIBILITY_SOURCE, bundlerVersion, bundlerSeries, compareBundler, bundlerPinBelowFloor, contiguousBundlerHop, validateBundlerLadder } from "./bundler-compat.js";
 
 const rubyVersion = /^\d+\.\d+(?:\.\d+)?$/;
 const railsVersion = /^\d+(?:\.\d+)+$/;
@@ -74,6 +76,31 @@ export function beginRailsBridgeRun({ root = process.cwd(), rubyReportPath, dryR
   return { ...plan, reportPath, report, lock };
 }
 
+export function beginBundlerBridgeRun({ root = process.cwd(), rubyReportPath, dryRun = false, stopAfterHop = false } = {}) {
+  const rubyRun = readRun(root, rubyReportPath);
+  if (rubyRun.reportType?.endsWith("_bridge") || rubyRun.phase !== "blocked" || rubyRun.status !== "blocked" || !rubyRun.bundlerBridge) throw new Error("A Bundler bridge can start only from a blocked Ruby run with an approved Bundler compatibility bridge.");
+  const preflight = inspectWorktree(root); const inventory = inventoryProject(root); const supplyChain = inspectSupplyChain(root); const gitCapabilities = inspectGitCapabilities(root); const bridge = rubyRun.bundlerBridge;
+  const plan = { preflight, inventory, supplyChain, gitCapabilities, bridge, dryRun, stopAfterHop };
+  if (dryRun) return plan;
+  if (!preflight.ok || preflight.mode !== "linked-worktree") throw new Error("A durable Bundler bridge requires a supported linked Git worktree.");
+  if (bundlerSeries(inventory.bundler?.bundledWith ?? "") !== bundlerSeries(bridge.bundlerFrom)) throw new Error("The current Gemfile.lock must still record the Bundler version recorded by the blocked Ruby run.");
+  if (preflight.branch !== rubyRun.branch || preflight.sha !== rubyRun.expectedHead) throw new Error("Bundler bridge must start on the blocked Ruby run's recorded branch and checkpoint SHA.");
+  const reportPath = path.join(".ruby-upgrades", "runs", runName());
+  const report = { schemaVersion: 2, validationReceiptsRequired: true, reportType: "bundler_bridge", runId: crypto.randomUUID(), title: `Bundler bridge ${bridge.bundlerFrom} to ${bridge.bundlerTo}`, status: "in_progress", phase: "initialized", startedAt: new Date().toISOString(), targetBundler: bridge.bundlerTo, targetBundlerPinnedAt: new Date().toISOString(), targetRuby: bridge.rubyTo, branch: preflight.branch ?? null, worktreeRoot: preflight.root ?? root, startingSha: preflight.sha ?? null, expectedHead: preflight.sha ?? null, control: { stopAfterHop }, inventory, supplyChain, gitCapabilities, bridge: { rubyReportPath, rubyRunId: rubyRun.runId, rubyFrom: bridge.rubyFrom, rubyTo: bridge.rubyTo, bundlerFrom: bridge.bundlerFrom, bundlerTo: bridge.bundlerTo, minimumBundler: bridge.minimumBundler, compatibilitySource: bridge.compatibilitySource, approvedAt: bridge.recordedAt }, research: { ladder: [], citations: [] }, riskDecisions: [], requiredRisks: requiredRisksFor(supplyChain, gitCapabilities), summary: [`Bundler bridge initialized from a blocked Ruby hop; researched floor ${bridge.minimumBundler}.`], iterations: [], sessionSummary: "" };
+  const lock = acquireRunLock(root, reportPath); report.lockNonce = lock.nonce;
+  try { writeRun(root, reportPath, report); } catch (error) { releaseRunLock(root, reportPath, lock.nonce); throw error; }
+  return { ...plan, reportPath, report, lock };
+}
+
+export function recordBundlerResearch({ root = process.cwd(), reportPath, ladder, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "bundler_bridge") throw new Error("Bundler research belongs only to a Bundler bridge report.");
+  const problem = validateBundlerLadder({ ladder, pinned: run.bridge.bundlerFrom, target: run.targetBundler });
+  if (problem) throw new Error(problem);
+  if (!Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("Bundler research requires at least one HTTPS official-source citation.");
+  run.research = { ladder, citations }; writeRun(root, reportPath, run); return run;
+}
+
 export function recordResearch({ root = process.cwd(), reportPath, ladder, citations }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
   if (!Array.isArray(ladder) || !ladder.length || ladder.some((version) => !rubyVersion.test(version))) throw new Error("Research requires a Ruby-version ladder.");
@@ -98,6 +125,31 @@ export function recordRiskDecision({ root = process.cwd(), reportPath, risk, dec
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); run.riskDecisions.push({ risk, decision, evidence, recordedAt: new Date().toISOString() }); writeRun(root, reportPath, run); return run;
 }
 
+// A Bundler bridge records the same kind of decision the Rails bridge does: the
+// project's own pin cannot cross the researched Ruby hop, so the change happens
+// in its own separately scoped run. What differs is the evidence -- a Rails hop
+// produces a reviewable `app:update` receipt, while a Bundler hop produces a
+// lockfile change that must be confirmed against the version actually executed.
+export function recordBundlerBridge({ root = process.cwd(), reportPath, rubyFrom, rubyTo, bundlerFrom, bundlerTo, minimumBundler, rationale, citations }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (!["research_complete", "committed"].includes(run.phase)) throw new Error("Record a Bundler compatibility bridge only after research or a committed Ruby checkpoint and before a blocked Ruby hop.");
+  if (run.frameworkBridge || run.bundlerBridge) throw new Error("This run already has an approved compatibility bridge; complete it in a separately scoped run.");
+  if (![rubyFrom, rubyTo].every((version) => rubyVersion.test(version)) || ![bundlerFrom, bundlerTo, minimumBundler].every((version) => bundlerVersion.test(version))) throw new Error("A Bundler compatibility bridge requires Ruby from/to and Bundler from/to/floor versions.");
+  if (series(rubyFrom) !== series(run.iterations.at(-1)?.to ?? run.research.ladder[0]) || series(rubyTo) !== series(run.research.ladder[run.research.ladder.findIndex((version) => series(version) === series(rubyFrom)) + 1])) throw new Error("Bundler compatibility bridge must describe the next researched Ruby hop.");
+  if (series(bundlerFrom) !== series(run.inventory.bundler?.bundledWith ?? "")) throw new Error("A Bundler compatibility bridge must begin at the version recorded in the project's BUNDLED WITH.");
+  // Without this the bridge could be approved for a pin that already satisfies
+  // the floor, which would block a hop for no reason. It is deliberately the
+  // last check before approval, so the message names the actual pin and floor
+  // rather than a generic validation failure.
+  const pin = run.inventory.bundler?.bundledWith ?? bundlerFrom;
+  if (!bundlerPinBelowFloor({ pinned: pin, minimum: minimumBundler })) throw new Error(`Bundler ${pin} is not below the researched floor ${minimumBundler}; approving a bridge would block the hop without cause.`);
+  if (compareBundler(bundlerTo, minimumBundler) < 0) throw new Error("The bridge target Bundler must be at or above the researched minimum floor.");
+  if (!rationale || !Array.isArray(citations) || !citations.length || citations.some((citation) => !citation?.title || !/^https:\/\//.test(citation.url ?? ""))) throw new Error("A Bundler compatibility bridge requires a rationale and HTTPS citations.");
+  run.bundlerBridge = { status: "approved", rubyFrom, rubyTo, bundlerFrom, bundlerTo, minimumBundler, compatibilitySource: BUNDLER_COMPATIBILITY_SOURCE, rationale, citations, recordedAt: new Date().toISOString() };
+  run.summary = [...run.summary, `User approved a separately scoped Bundler ${bundlerFrom} → ${bundlerTo} bridge before Ruby ${rubyFrom} → ${rubyTo}, on a researched floor of ${minimumBundler}.`];
+  writeRun(root, reportPath, run); return run;
+}
+
 export function recordFrameworkBridge({ root = process.cwd(), reportPath, rubyFrom, rubyTo, railsFrom, railsTo, rationale, citations }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
   if (!["research_complete", "committed"].includes(run.phase)) throw new Error("Record a Rails compatibility bridge only after research or a committed Ruby checkpoint and before a blocked Ruby hop.");
@@ -114,7 +166,7 @@ export function recordFrameworkBridge({ root = process.cwd(), reportPath, rubyFr
 
 function recordIterationInternal({ root = process.cwd(), reportPath, iteration, executed = false }) {
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
-  if (run.reportType === "rails_bridge") throw new Error("Use record-rails-iteration for a Rails bridge report.");
+  if (run.reportType?.endsWith("_bridge")) throw new Error(`Use the ${run.reportType === "rails_bridge" ? "Rails" : "Bundler"} bridge iteration recorder for a bridge report.`);
   if (run.validationReceiptsRequired && !executed) throw new Error("New reports require record-executed-iteration so validation receipts are created by the executor.");
   if (run.phase !== "research_complete" && run.phase !== "committed") throw new Error("Record iterations only after research or a prior checkpoint.");
   assertApprovedRisks(run);
@@ -190,6 +242,27 @@ export function discardLastRailsIteration({ root = process.cwd(), reportPath, re
   writeRun(root, reportPath, run); return run;
 }
 
+// A Bundler hop is evidenced by what it changed and what actually ran. `bundle
+// lock --bundler` rewrites the `BUNDLED WITH` pin, and the runtime attests the
+// Bundler that executed the tests; requiring both to agree is what stops a hop
+// being recorded on the strength of a lockfile edit alone.
+export function recordExecutedBundlerIteration({ root = process.cwd(), reportPath, iteration, validationCommandId, executed = false }) {
+  const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
+  if (run.reportType !== "bundler_bridge" || !["research_complete", "committed"].includes(run.phase)) throw new Error("Record Bundler iterations only after Bundler research or a prior Bundler checkpoint.");
+  assertApprovedRisks(run);
+  if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before the next iteration.");
+  const expectedFrom = run.iterations.at(-1)?.to ?? run.research.ladder[0];
+  const index = run.research.ladder.findIndex((version) => bundlerSeries(version) === bundlerSeries(expectedFrom));
+  const expectedTo = run.research.ladder[index + 1];
+  if (!iteration || index < 0 || !expectedTo || bundlerSeries(iteration.from) !== bundlerSeries(expectedFrom) || bundlerSeries(iteration.to) !== bundlerSeries(expectedTo)) throw new Error("Iteration must advance exactly one researched Bundler series from the prior ladder point.");
+  const receipt = executeValidation({ root, inventory: run.inventory, commandId: validationCommandId, expectedRuntime: { runId: run.runId, reportPath } });
+  if (receipt.kind !== "test" || receipt.exitCode !== 0 || receipt.testEvidence?.passed !== true) throw new Error(`Validation failed; receipt ${receipt.id} was not recorded as a passing hop.`);
+  const pinned = inventoryBundledWith(root);
+  if (bundlerSeries(pinned ?? "") !== bundlerSeries(iteration.to)) throw new Error(`Gemfile.lock still records Bundler ${pinned ?? "none"}; a hop to ${iteration.to} requires the BUNDLED WITH pin to be rewritten first.`);
+  if (bundlerSeries(receipt.environment?.bundlerVersion ?? "") !== bundlerSeries(iteration.to)) throw new Error(`Validation executed Bundler ${receipt.environment?.bundlerVersion ?? "an unrecorded version"}, not ${iteration.to}. Re-prepare the target runtime on the new Bundler before recording this hop.`);
+  run.iterations.push({ ...iteration, status: "complete", lockfilePin: pinned }); writeRun(root, reportPath, run); return run;
+}
+
 export function recordDependencyReview({ root = process.cwd(), reportPath, compatibility, licenses }) {
   if (!compatibility?.trim() || !licenses?.trim()) throw new Error("Dependency review requires compatibility and license findings.");
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce);
@@ -205,7 +278,8 @@ function validRailsReviewForExecution(review, receipt) { return review?.command
 function validationPreflight(root, reportPath, rails) {
   const run = readRun(root, reportPath);
   assertRunLock(root, reportPath, run.lockNonce);
-  if (Boolean(run.reportType === "rails_bridge") !== rails || !["research_complete", "committed"].includes(run.phase)) throw new Error("Validation can run only for the active report type after research or a prior checkpoint.");
+  const activeType = run.reportType === "rails_bridge" ? "rails_bridge" : run.reportType === "bundler_bridge" ? "bundler_bridge" : "ruby";
+  if ((rails ? "rails_bridge" : "ruby") !== activeType || !["research_complete", "committed"].includes(run.phase)) throw new Error("Validation can run only for the active report type after research or a prior checkpoint.");
   assertApprovedRisks(run);
   if (run.iterations.length && (run.phase !== "committed" || !run.iterations.at(-1).checkpointSha)) throw new Error("Each iteration requires exactly one checkpoint before validation can run again.");
   return run;
@@ -213,7 +287,7 @@ function validationPreflight(root, reportPath, rails) {
 
 function assertCompletion(run) {
   const final = run.iterations.at(-1);
-  const target = run.reportType === "rails_bridge" ? run.targetRails : run.targetRuby;
+  const target = run.reportType === "rails_bridge" ? run.targetRails : run.reportType === "bundler_bridge" ? run.targetBundler : run.targetRuby;
   if (!final || series(final.to) !== series(target)) throw new Error("A run can complete only after the final validated iteration reaches its pinned target.");
   if (series(run.research.ladder.at(-1)) !== series(target)) throw new Error("Research ladder does not reach its pinned target.");
   if (hasUnapprovedRisks(run)) throw new Error("Unresolved risks prevent completion.");
@@ -228,14 +302,14 @@ function verifyCheckpoint(root, reportPath, run, commitSha) {
   if (git(root, ["rev-parse", `${head}^`]) !== run.expectedHead) throw new Error("Checkpoint must be a direct child of the prior recorded checkpoint.");
   const iteration = run.iterations.at(-1);
   const message = git(root, ["log", "-1", "--format=%B"]);
-  const prefix = run.reportType === "rails_bridge" ? "Rails" : "Ruby";
-  if (!message.includes(`${prefix}-Upgrade-Report: ${reportPath}`) || !message.includes(`${prefix}-Upgrade-Hop: ${iteration.from}->${iteration.to}`) || (iteration.validationReceipts?.length && !message.includes(`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`)) || (prefix === "Rails" && (!message.includes(`Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`) || !message.includes(`Rails-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`)))) throw new Error("Checkpoint commit does not carry the required run and hop trailers.");
+  const prefix = run.reportType === "rails_bridge" ? "Rails" : run.reportType === "bundler_bridge" ? "Bundler" : "Ruby";
+  if (!message.includes(`${prefix}-Upgrade-Report: ${reportPath}`) || !message.includes(`${prefix}-Upgrade-Hop: ${iteration.from}->${iteration.to}`) || (iteration.validationReceipts?.length && !message.includes(`Validation-Receipt-Digest: sha256:${receiptDigest(iteration.validationReceipts)}`)) || (prefix === "Rails" && (!message.includes(`Rails-App-Update-Reviewed: ${iteration.from}->${iteration.to}`) || !message.includes(`Rails-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`))) || (prefix === "Bundler" && !message.includes(`Bundler-Bridge-Ruby-Report: ${run.bridge.rubyReportPath}`))) throw new Error("Checkpoint commit does not carry the required run and hop trailers.");
 }
 
 export function transitionRun({ root = process.cwd(), reportPath, phase, note = "", commitSha = "" }) {
   if (!Object.hasOwn(transitions, phase)) throw new Error(`Unknown run phase: ${phase}.`);
   const run = readRun(root, reportPath); assertRunLock(root, reportPath, run.lockNonce); const current = run.phase;
-  if (current === "blocked" && run.frameworkBridge) throw new Error("A Ruby run blocked by a Rails bridge is terminal; complete the bridge and start a fresh Ruby run.");
+  if (current === "blocked" && (run.frameworkBridge || run.bundlerBridge)) throw new Error("A Ruby run blocked by an approved compatibility bridge is terminal; complete that bridge and start a fresh Ruby run.");
   if (!transitions[current]?.includes(phase)) throw new Error(`Cannot transition from ${current} to ${phase}.`);
   if (phase === "research_complete" && (!run.research.ladder.length || !run.research.citations.length)) throw new Error("Record research and citations before completing research.");
   if (phase === "hop_validated" && (run.iterations.at(-1)?.tests?.passed !== true || !run.iterations.at(-1)?.validationReceipts?.length)) throw new Error("A hop requires passing tests and executed validation receipts.");
@@ -258,7 +332,7 @@ export function transitionRun({ root = process.cwd(), reportPath, phase, note =
 export function resumeRun({ root = process.cwd(), reportPath, continueAfterHop = false }) {
   const run = readRun(root, reportPath);
   if (run.status === "complete") throw new Error("This run is complete; start a new run instead.");
-  if (run.frameworkBridge && run.phase === "blocked") throw new Error("This Ruby run is blocked by an approved Rails bridge and cannot resume. Complete the linked Rails bridge, then begin a fresh Ruby run.");
+  if ((run.frameworkBridge || run.bundlerBridge) && run.phase === "blocked") throw new Error("This Ruby run is blocked by an approved compatibility bridge and cannot resume. Complete the linked bridge, then begin a fresh Ruby run.");
   if (run.phase === "paused" && !transitions.paused.includes(run.resumePhase)) throw new Error("Paused run has no safe resume phase.");
   if (run.control.stopAfterHop && run.iterations.length >= 1 && run.resumePhase === "committed" && !continueAfterHop) throw new Error("This run stopped after its requested hop. Resume with explicit --continue-after-hop only after user review.");
   if (continueAfterHop) run.control.stopAfterHop = false;

package/src/dashboard-page.js

@@ -11,6 +11,6 @@ const testValue=(tests,key,fallback='—')=>tests&&tests[key]!==undefined&&tests
 fetch('/api/runs').then(response=>response.json()).then(runs=>{
  const app=document.querySelector('#app');
  if(!runs.length){app.innerHTML='<article class="card"><b>No upgrade runs yet.</b><p>Run <code>/ruby-upgrade</code> from a linked Git worktree. Evidence will appear under <code>.ruby-upgrades/runs/</code>.</p></article>';return;}
- app.innerHTML=runs.map(run=>{const iterations=run.iterations||[];const latest=iterations.at(-1)||{};const tests=latest.tests||{};const commits=(run.localCommits||[]).map(sha=>'<code>'+esc(sha)+'</code>').join(' ')||'No local commit found yet.';const target=run.reportType==='rails_bridge'?'Rails '+(run.targetRails||'target unknown'):'Ruby '+(run.targetRuby||'target unknown');const bridge=run.reportType==='rails_bridge'?'<p><b>Blocked Ruby hop:</b> '+esc(run.bridge?.rubyFrom)+' → '+esc(run.bridge?.rubyTo)+' · <code>'+esc(run.bridge?.rubyReportPath)+'</code></p>':'';const details=iterations.map(iteration=>{const itTests=iteration.tests||{};const fixes=(iteration.fixes||[]).map(fix=>'<li><b>'+esc((fix.files||[]).join(', ')||'Migration fix')+'</b><br>'+esc(fix.explanation)+'</li>').join('')||'<li>No code or dependency fixes recorded.</li>';const citations=(iteration.citations||[]).map(citation=>'<a href="'+safeUrl(citation.url)+'" target="_blank" rel="noreferrer">'+esc(citation.title||citation.url)+'</a>').join(' · ')||'No citations recorded.';const appUpdate=iteration.appUpdateReview?'<p><small>app:update: '+esc(iteration.appUpdateReview.outcome)+' — '+esc(iteration.appUpdateReview.summary)+'</small></p>':'';const receipts=(iteration.validationReceipts||[]).map(receipt=>{const digest=receipt.output&&receipt.output.redactedSha256?receipt.output.redactedSha256.slice(0,16):'';const meta=['kind:'+esc(receipt.kind||'—'),'exit:'+esc(receipt.exitCode??'—'),(receipt.durationMs?'ms:'+esc(receipt.durationMs):'')].filter(Boolean).join(' · ');return '<li><code>'+meta+'</code>'+((receipt.testEvidence&&receipt.testEvidence.passed===true)?' <b>[PASS]</b>':'')+'<br><small>digest <code>'+esc(digest||'—')+'</code> · '+(receipt.environment?esc(receipt.environment.imageRef||receipt.environment.ruby||'')+' · <code>'+esc(receipt.environment.imageId||receipt.environment.id||'')+'</code>':'')+'</small></li>';}).join('');const review=iteration.dependencyReview&&iteration.dependencyReview.completed?'<p><small>Dependency review: '+esc(iteration.dependencyReview.compatibility||'completed')+(iteration.dependencyReview.licenses?' · '+esc(iteration.dependencyReview.licenses):'')+'</small></p>':'';return '<section class="iteration"><b>'+esc(iteration.from)+' → '+esc(iteration.to)+' · '+esc(iteration.status)+'</b><div class="grid">'+metric('Test result',itTests.passed===true?'Passed':itTests.passed===false?'Failed':'—')+metric('Smoke check',testValue(itTests,'smoke'))+metric('Coverage',testValue(itTests,'coveragePercent',null)===null?'—':testValue(itTests,'coveragePercent')+'%')+'</div><ul>'+fixes+'</ul>'+review+((iteration.validationReceipts&&iteration.validationReceipts.length)?'<p><b>Receipts</b></p><ul>'+receipts+'</ul>':'')+appUpdate+'<br><small>Sources: '+citations+'</small></section>';}).join('');return '<article class="card"><span class="tag">'+esc(run.status||'unknown')+'</span><span class="tag">'+esc(target)+'</span><h2>'+esc(run.title||run.file)+'</h2><p class="sub">'+esc(run.startedAt||'Unknown start')+' · '+esc(run.branch||'Unknown branch')+'</p><div class="grid">'+metric('Tests',testValue(tests,'count'))+metric('Coverage',testValue(tests,'coveragePercent',null)===null?'—':testValue(tests,'coveragePercent')+'%')+metric('Duration',testValue(tests,'durationSeconds',null)===null?'—':testValue(tests,'durationSeconds')+'s')+metric('Smoke check',testValue(tests,'smoke'))+'</div><pre>'+esc((run.summary||[]).join('\n'))+'</pre>'+bridge+details+'<p><b>Local commits:</b> '+commits+'</p><p><b>Session:</b> '+esc(run.sessionSummary||'—')+'</p></article>';}).join('');
+ app.innerHTML=runs.map(run=>{const iterations=run.iterations||[];const latest=iterations.at(-1)||{};const tests=latest.tests||{};const commits=(run.localCommits||[]).map(sha=>'<code>'+esc(sha)+'</code>').join(' ')||'No local commit found yet.';const target=run.reportType==='rails_bridge'?'Rails '+(run.targetRails||'target unknown'):run.reportType==='bundler_bridge'?'Bundler '+(run.targetBundler||'target unknown'):'Ruby '+(run.targetRuby||'target unknown');const advisories=(run.advisories||[]).map(item=>'<li><span class="tag">'+esc(item.area)+'</span> <b>'+esc(item.title)+'</b><br><small>'+esc(item.detail)+'</small><br><small>Evidence: <code>'+esc(item.evidence)+'</code> · '+esc(item.confidence)+'</small></li>').join('')||'<li><small>No infrastructure inconsistencies detected against the current worktree.</small></li>';const advisoryBlock='<p><b>Infrastructure review (advisory)</b> <small>— about files this run did not change; nothing here blocks the upgrade</small></p><ul>'+advisories+'</ul>';const bridge=run.bridge?'<p><b>Blocked Ruby hop:</b> '+esc(run.bridge.rubyFrom)+' → '+esc(run.bridge.rubyTo)+(run.bridge.minimumBundler?' · researched Bundler floor <code>'+esc(run.bridge.minimumBundler)+'</code>':'')+' · <code>'+esc(run.bridge.rubyReportPath)+'</code></p>':'';const details=iterations.map(iteration=>{const itTests=iteration.tests||{};const fixes=(iteration.fixes||[]).map(fix=>'<li><b>'+esc((fix.files||[]).join(', ')||'Migration fix')+'</b><br>'+esc(fix.explanation)+'</li>').join('')||'<li>No code or dependency fixes recorded.</li>';const citations=(iteration.citations||[]).map(citation=>'<a href="'+safeUrl(citation.url)+'" target="_blank" rel="noreferrer">'+esc(citation.title||citation.url)+'</a>').join(' · ')||'No citations recorded.';const appUpdate=iteration.appUpdateReview?'<p><small>app:update: '+esc(iteration.appUpdateReview.outcome)+' — '+esc(iteration.appUpdateReview.summary)+'</small></p>':'';const receipts=(iteration.validationReceipts||[]).map(receipt=>{const digest=receipt.output&&receipt.output.redactedSha256?receipt.output.redactedSha256.slice(0,16):'';const meta=['kind:'+esc(receipt.kind||'—'),'exit:'+esc(receipt.exitCode??'—'),(receipt.durationMs?'ms:'+esc(receipt.durationMs):'')].filter(Boolean).join(' · ');return '<li><code>'+meta+'</code>'+((receipt.testEvidence&&receipt.testEvidence.passed===true)?' <b>[PASS]</b>':'')+'<br><small>digest <code>'+esc(digest||'—')+'</code> · '+(receipt.environment?esc(receipt.environment.imageRef||receipt.environment.ruby||'')+' · <code>'+esc(receipt.environment.imageId||receipt.environment.id||'')+'</code>':'')+'</small></li>';}).join('');const pin=iteration.lockfilePin?'<p><small>BUNDLED WITH: <code>'+esc(iteration.lockfilePin)+'</code></small></p>':'';const review=iteration.dependencyReview&&iteration.dependencyReview.completed?'<p><small>Dependency review: '+esc(iteration.dependencyReview.compatibility||'completed')+(iteration.dependencyReview.licenses?' · '+esc(iteration.dependencyReview.licenses):'')+'</small></p>':'';return '<section class="iteration"><b>'+esc(iteration.from)+' → '+esc(iteration.to)+' · '+esc(iteration.status)+'</b><div class="grid">'+metric('Test result',itTests.passed===true?'Passed':itTests.passed===false?'Failed':'—')+metric('Smoke check',testValue(itTests,'smoke'))+metric('Coverage',testValue(itTests,'coveragePercent',null)===null?'—':testValue(itTests,'coveragePercent')+'%')+'</div><ul>'+fixes+'</ul>'+pin+review+((iteration.validationReceipts&&iteration.validationReceipts.length)?'<p><b>Receipts</b></p><ul>'+receipts+'</ul>':'')+appUpdate+'<br><small>Sources: '+citations+'</small></section>';}).join('');return '<article class="card"><span class="tag">'+esc(run.status||'unknown')+'</span><span class="tag">'+esc(target)+'</span><h2>'+esc(run.title||run.file)+'</h2><p class="sub">'+esc(run.startedAt||'Unknown start')+' · '+esc(run.branch||'Unknown branch')+'</p><div class="grid">'+metric('Tests',testValue(tests,'count'))+metric('Coverage',testValue(tests,'coveragePercent',null)===null?'—':testValue(tests,'coveragePercent')+'%')+metric('Duration',testValue(tests,'durationSeconds',null)===null?'—':testValue(tests,'durationSeconds')+'s')+metric('Smoke check',testValue(tests,'smoke'))+'</div><pre>'+esc((run.summary||[]).join('\n'))+'</pre>'+bridge+advisoryBlock+details+'<p><b>Local commits:</b> '+commits+'</p><p><b>Session:</b> '+esc(run.sessionSummary||'—')+'</p></article>';}).join('');
 }).catch(error=>{document.querySelector('#app').innerHTML='<article class="card">Could not load upgrade reports: '+esc(error.message)+'</article>';});
 </script></body></html>`;

package/src/dashboard.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { execFileSync } from "node:child_process";
 import { dashboardPage } from "./dashboard-page.js";
 import { readRun } from "./run-state.js";
+import { advisoryFindings } from "./advisory.js";
 
 const MAX_RUN_FILES = 250;
 const MAX_RUN_BYTES = 1024 * 1024;
@@ -53,8 +54,15 @@ export function startDashboard({ root = process.cwd(), port = 0 } = {}) {
       return response.end("Method not allowed");
     }
     if (request.url === "/api/runs") {
+      // Advisory findings are recomputed per request rather than stored in the
+      // report. They describe the worktree as it stands now, so a stale value in
+      // a historical run would be worse than no value at all.
+      const runs = readUpgradeRuns(root).map((run) => {
+        try { return { ...run, advisories: advisoryFindings({ root, run, inventory: run.inventory ?? {} }) }; }
+        catch { return { ...run, advisories: [] }; }
+      });
       response.writeHead(200, { ...securityHeaders, "content-type": "application/json; charset=utf-8" });
-      return response.end(JSON.stringify(readUpgradeRuns(root)));
+      return response.end(JSON.stringify(runs));
     }
     if (request.url === "/" || request.url === "/index.html") {
       response.writeHead(200, { ...securityHeaders, "content-type": "text/html; charset=utf-8" });

package/src/inventory.js

@@ -23,7 +23,11 @@ export function inventoryProject(root = process.cwd()) {
   const deploy = ["Dockerfile", "docker-compose.yml", "Procfile", "app.json", "render.yaml", "fly.toml", "config/deploy.yml"].filter((file) => exists(root, file));
   return {
     root, supported: exists(root, "Gemfile"), framework: rails ? "rails" : "ruby", testFramework: rspec ? "rspec" : minitest ? "minitest" : "unknown",
-    rubyDeclarations, rails: rails ? { declaredVersion: declaredRails, resolvedVersion: resolvedRails } : null, recommendedCommands: commands, ci, deploy,
+    rubyDeclarations, rails: rails ? { declaredVersion: declaredRails, resolvedVersion: resolvedRails } : null,
+    // Bundler switches to the version under `BUNDLED WITH`, so this is the
+    // version that will actually run -- not merely the newest one installed.
+    bundler: { bundledWith: lockfile.match(/^BUNDLED WITH\s*\r?\n\s+(\d+(?:\.\d+)+)/m)?.[1] ?? null },
+    recommendedCommands: commands, ci, deploy,
     requiresDecision: !exists(root, "Gemfile") || commands.length === 0,
     reason: !exists(root, "Gemfile") ? "No Gemfile found." : commands.length === 0 ? "No recognized test adapter found." : undefined
   };

package/src/run-state.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { advisoryFindings } from "./advisory.js";
 
 const SECRET_VALUE = /(?:gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|\bAKIA[0-9A-Z]{16}\b|-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----|\b(?:xox[baprs]-|npm_|glpat-)[A-Za-z0-9_-]{16,})/g;
 const SECRET_KEY = /(?:password|secret|token|api[_-]?key|credential|authorization)/i;
@@ -30,6 +31,8 @@ export function redactSourceUrl(value) {
 
 function validVersion(value) { return typeof value === "string" && /^\d+\.\d+(?:\.(?:\d+|x))?$/.test(value); }
 function validRailsVersion(value) { return typeof value === "string" && /^\d+(?:\.\d+)+$/.test(value); }
+function validBundlerVersion(value) { return typeof value === "string" && /^\d+(?:\.\d+)*$/.test(value); }
+const bundlerSeriesOf = (value) => String(value ?? "").split(".").slice(0, 2).join(".");
 function validCitation(value) { return value && typeof value.title === "string" && /^https:\/\//.test(value.url ?? ""); }
 function safeFiles(files) { return Array.isArray(files) && files.every((file) => typeof file === "string" && !path.isAbsolute(file) && !file.includes("..")); }
 function validAppUpdateReview(review) { return review && review.command === "bin/rails app:update" && typeof review.receiptId === "string" && !Number.isNaN(Date.parse(review.executedAt ?? "")) && !Number.isNaN(Date.parse(review.reviewedAt ?? "")) && validFingerprint(review.worktree) && ["no_changes", "changes_applied", "changes_deferred"].includes(review.outcome) && safeFiles(review.files) && typeof review.summary === "string" && Boolean(review.summary); }
@@ -59,6 +62,31 @@ function receiptErrors(iteration, index, rails, required, errors) {
   }
 }
 
+function validateBundlerBridge(run, errors) {
+  for (const key of ["runId", "title", "startedAt", "targetBundler", "targetBundlerPinnedAt", "phase", "status", "bridge"]) if (!run[key]) errors.push(`Bundler bridge report requires ${key}.`);
+  if (!validBundlerVersion(run.targetBundler)) errors.push("targetBundler must be a Bundler version.");
+  if (typeof run.runId !== "string" || !/^[a-f0-9-]{36}$/i.test(run.runId ?? "")) errors.push("runId must be a UUID.");
+  if (run.startedAt && Number.isNaN(Date.parse(run.startedAt))) errors.push("startedAt must be ISO-8601.");
+  if (!statuses.has(run.status) || !phases.has(run.phase)) errors.push("Bundler bridge has invalid status or phase.");
+  if (run.lockNonce !== undefined && (typeof run.lockNonce !== "string" || !/^[a-f0-9-]{36}$/i.test(run.lockNonce))) errors.push("lockNonce must be a UUID.");
+  if (run.targetBundlerPinnedAt && Number.isNaN(Date.parse(run.targetBundlerPinnedAt))) errors.push("targetBundlerPinnedAt must be ISO-8601.");
+  // The link back to the blocked Ruby run is what makes the bridge separately
+  // scoped rather than a second phase of the same run, so it must be complete.
+  if (!run.bridge || typeof run.bridge !== "object" || typeof run.bridge.rubyReportPath !== "string" || !/^[a-f0-9-]{36}$/i.test(run.bridge.rubyRunId ?? "") || !validVersion(run.bridge.rubyFrom) || !validVersion(run.bridge.rubyTo) || !validBundlerVersion(run.bridge.bundlerFrom) || !validBundlerVersion(run.bridge.bundlerTo) || !validBundlerVersion(run.bridge.minimumBundler)) errors.push("Bundler bridge report has invalid Ruby-run linkage.");
+  if (!Array.isArray(run.research?.ladder) || run.research.ladder.some((version) => !validBundlerVersion(version))) errors.push("Bundler bridge research.ladder must contain Bundler versions.");
+  if (!Array.isArray(run.research?.citations) || run.research.citations.some((citation) => !validCitation(citation))) errors.push("research.citations must contain HTTPS citations.");
+  if (!Array.isArray(run.iterations)) errors.push("iterations must be an array.");
+  for (const [index, iteration] of (run.iterations ?? []).entries()) {
+    if (!validBundlerVersion(iteration?.from) || !validBundlerVersion(iteration?.to) || iteration?.status !== "complete") errors.push(`Bundler iteration ${index + 1} is invalid.`);
+    if (!safeFiles(iteration?.files) || iteration?.tests?.passed !== true || !iteration.tests?.command || !iteration.tests?.smoke || !Array.isArray(iteration?.citations) || !iteration.citations.length || !Array.isArray(iteration?.fixes) || iteration.fixes.some((fix) => !safeFiles(fix.files) || !fix.explanation)) errors.push(`Bundler iteration ${index + 1} lacks required evidence.`);
+    // The pin the hop actually produced, so a later reader can see the lockfile
+    // agreed with the validated version instead of taking it on trust.
+    if (!validBundlerVersion(iteration?.lockfilePin) || bundlerSeriesOf(iteration.lockfilePin) !== bundlerSeriesOf(iteration.to)) errors.push(`Bundler iteration ${index + 1} must record the BUNDLED WITH pin it produced.`);
+    if (iteration?.checkpointSha !== undefined && !/^[a-f0-9]{40}$/i.test(iteration.checkpointSha)) errors.push(`Bundler iteration ${index + 1} checkpointSha must be a Git SHA.`);
+    receiptErrors(iteration, index, false, run.validationReceiptsRequired === true, errors);
+  }
+}
+
 function validateRailsBridge(run, errors) {
   for (const key of ["runId", "title", "startedAt", "targetRails", "targetRailsPinnedAt", "phase", "status", "bridge"]) if (!run[key]) errors.push(`Rails bridge report requires ${key}.`);
   if (!validRailsVersion(run.targetRails)) errors.push("targetRails must be a Rails version.");
@@ -88,6 +116,7 @@ export function validateRun(run) {
   if (run.schemaVersion !== 2) errors.push("Report schemaVersion must be 2.");
   if (run.validationReceiptsRequired !== undefined && run.validationReceiptsRequired !== true) errors.push("validationReceiptsRequired must be true when present.");
   if (run.reportType === "rails_bridge") { validateRailsBridge(run, errors); return { valid: errors.length === 0, errors }; }
+  if (run.reportType === "bundler_bridge") { validateBundlerBridge(run, errors); return { valid: errors.length === 0, errors }; }
   if (run.reportType !== undefined && run.reportType !== "ruby") errors.push("Unknown reportType.");
   for (const key of ["runId", "title", "startedAt", "targetRuby", "targetPinnedAt", "phase", "status"]) if (!run[key]) errors.push(`Report requires ${key}.`);
   if (run.lockNonce !== undefined && (typeof run.lockNonce !== "string" || !/^[a-f0-9-]{36}$/i.test(run.lockNonce))) errors.push("lockNonce must be a UUID.");
@@ -109,6 +138,16 @@ export function validateRun(run) {
     if (typeof bridge?.rationale !== "string" || !bridge.rationale) errors.push("frameworkBridge requires a rationale.");
     if (!Array.isArray(bridge?.citations) || !bridge.citations.length || bridge.citations.some((citation) => !validCitation(citation))) errors.push("frameworkBridge requires HTTPS citations.");
   }
+  if (run.bundlerBridge !== undefined && run.bundlerBridge !== null) {
+    const bridge = run.bundlerBridge;
+    if (!bridge || typeof bridge !== "object" || bridge.status !== "approved") errors.push("bundlerBridge must be an approved compatibility decision.");
+    if (!validVersion(bridge?.rubyFrom) || !validVersion(bridge?.rubyTo) || !validBundlerVersion(bridge?.bundlerFrom) || !validBundlerVersion(bridge?.bundlerTo) || !validBundlerVersion(bridge?.minimumBundler)) errors.push("bundlerBridge requires Ruby from/to and Bundler from/to/floor versions.");
+    // The researched floor is what justifies blocking the hop, so its provenance
+    // has to be recorded rather than asserted.
+    if (typeof bridge?.compatibilitySource !== "string" || !/^https:\/\//.test(bridge.compatibilitySource)) errors.push("bundlerBridge requires the official compatibility source.");
+    if (typeof bridge?.rationale !== "string" || !bridge.rationale) errors.push("bundlerBridge requires a rationale.");
+    if (!Array.isArray(bridge?.citations) || !bridge.citations.length || bridge.citations.some((citation) => !validCitation(citation))) errors.push("bundlerBridge requires HTTPS citations.");
+  }
   for (const [index, iteration] of (run.iterations ?? []).entries()) {
     if (!validVersion(iteration?.from) || !validVersion(iteration?.to)) errors.push(`Iteration ${index + 1} requires Ruby from/to versions.`);
     if (iteration?.status !== "complete") errors.push(`Iteration ${index + 1} must be complete.`);
@@ -173,13 +212,63 @@ export function writeRun(root, relativePath, run) {
   const markdown = file.replace(/\.json$/, ".md");
   if (fs.existsSync(markdown) && (!fs.lstatSync(markdown).isFile() || fs.lstatSync(markdown).isSymbolicLink())) throw new RunStateError("Markdown evidence must be a regular file inside the worktree.", "unsafe-report-path");
   const safe = redact(run);
-  const target = safe.reportType === "rails_bridge" ? `- **Target Rails:** ${safe.targetRails}` : `- **Target Ruby:** ${safe.targetRuby}`;
-  const markdownBody = `# ${safe.title}\n\n- **Status:** ${safe.status}\n- **Phase:** ${safe.phase}\n${target}\n- **Started:** ${safe.startedAt}\n\n## Durable evidence\n\n\`\`\`json\n${JSON.stringify(safe, null, 2)}\n\`\`\`\n`;
+  const target = safe.reportType === "rails_bridge" ? `- **Target Rails:** ${safe.targetRails}` : safe.reportType === "bundler_bridge" ? `- **Target Bundler:** ${safe.targetBundler}` : `- **Target Ruby:** ${safe.targetRuby}`;
+  const followUps = followUpActions(safe);
+  const advisories = collectAdvisories(root, safe);
+  const followUpBlock = followUps.length
+    ? `\n## Follow-up actions\n\nThese are yours to take. Nothing below was verified by this run; the run cannot test your production topology.\n\n${followUps.map((item) => `- ${item}`).join("\n")}\n`
+    : "";
+  // Advisory only: never a gate. Rendered as its own section so it is obvious
+  // these are observations about the reader's infrastructure, not evidence the
+  // run collected about the app.
+  const advisoryBlock = advisories.length
+    ? `\n## Infrastructure review (advisory)\n\nRead-only observations about files this run did not change. Nothing here blocks the upgrade, and an intentional version pin that lags the app is legitimate. Confirm each against your actual deploy platform.\n\n| Area | Finding | Evidence | Basis |\n| --- | --- | --- | --- |\n${advisories.map((item) => `| ${item.area} | ${item.title}<br>${item.detail} | \`${item.evidence.replace(/\|/g, "\\|")}\` | ${item.confidence} |`).join("\n")}\n`
+    : "";
+  const markdownBody = `# ${safe.title}\n\n- **Status:** ${safe.status}\n- **Phase:** ${safe.phase}\n${target}\n- **Started:** ${safe.startedAt}\n${followUpBlock}${advisoryBlock}\n## Durable evidence\n\n\`\`\`json\n${JSON.stringify(safe, null, 2)}\n\`\`\`\n`;
   const markdownTemporary = path.join(path.dirname(markdown), `.${path.basename(markdown)}.${process.pid}.${crypto.randomUUID()}.tmp`);
   fs.writeFileSync(markdownTemporary, markdownBody, { mode: 0o600, flag: "wx" });
   fs.renameSync(markdownTemporary, markdown);
 }
 
+// Deployment-visible items a local test run provably cannot check. The isolated
+// runtime proves the code runs on the target Ruby in a container; it says nothing
+// about the host that will actually serve it. Each item is phrased as something
+// the reader must verify, never as something this run established, because a run
+// that "passed" here has not touched the real deploy target at all.
+function followUpActions(safe) {
+  const actions = [];
+  const last = safe.iterations?.at(-1);
+  if (last?.checkpointSha) actions.push(`Checkpoint \`${last.checkpointSha.slice(0, 7)}\` is validated locally but not deployed: push it and run your own staging check before it reaches production.`);
+  if (safe.phase === "blocked" || safe.status === "blocked") actions.push("This run is blocked. Resolve or explicitly approve the outstanding risks before treating the upgrade as complete.");
+  if (safe.frameworkBridge?.status === "approved") actions.push(`A Rails ${safe.frameworkBridge.railsFrom} → ${safe.frameworkBridge.railsTo} bridge was approved here but not performed. It needs its own separate run.`);
+  if (safe.bundlerBridge?.status === "approved") actions.push(`A Bundler ${safe.bundlerBridge.bundlerFrom} → ${safe.bundlerBridge.bundlerTo} bridge was approved here but not performed, on a researched floor of ${safe.bundlerBridge.minimumBundler}. Run \`begin-bundler-bridge\`, then restart the Ruby upgrade.`);
+  const environment = safe.environment;
+  if (environment?.type === "docker") {
+    // The single most common surprise: the container pins Bundler 2.4.22 and the
+    // app's own CI or deploy host may resolve a different one, changing which
+    // lockfile semantics apply.
+    actions.push(`The isolated runtime used Bundler ${environment.bundlerVersion ?? "a pinned version (unrecorded)"}${environment.bundlerVersion ? ` on Ruby ${environment.ruby}` : ""}. Confirm your deploy host and CI resolve the same Bundler version, or re-run \`bundle lock\` there.`);
+    actions.push(`Native gems were compiled for this container (${environment.database ?? "database"} on Ruby ${environment.ruby}). Rebuild native extensions on your deploy platform rather than copying \`node_modules\`-style build output.`);
+    actions.push(`Your deploy host must reach the real database directly; this run used an isolated ${environment.database} reachable only over a private Docker network and deliberately published no ports.`);
+    actions.push("Prepared containers and networks persist after the run by design. Remove them when you are done: `docker rm -f` and `docker network rm` on the names in `.ruby-upgrades/runtime.json`.");
+  }
+  actions.push("Review the validation receipts in `.ruby-upgrades/runs/` for the exact commands, exit codes, and test evidence before merging.");
+  return actions;
+}
+
+// Read the worktree's own infrastructure and compare it against what this run
+// changed. Wrapped because the report must still render when a worktree cannot
+// be inspected (an explicit `--report` from elsewhere, or a half-removed tree);
+// a missing advisory section must not fail a run whose evidence is already
+// recorded.
+export function collectAdvisories(root, safe) {
+  try {
+    return advisoryFindings({ root, run: safe, inventory: safe.inventory ?? {} });
+  } catch {
+    return [];
+  }
+}
+
 function lockPath(root) {
   try { return execFileSync("git", ["rev-parse", "--git-path", "opencode-ruby-upgrade.lock"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
   catch { return path.join(runsDirectory(root, true), ".run.lock"); }

package/src/target-runtime.js

@@ -46,27 +46,36 @@ function preparationResult(result) {
   return { sha256: crypto.createHash("sha256").update(output).digest("hex"), bytes: Buffer.byteLength(output) };
 }
 function bootstrap(spawn, runtime, db, rails) {
-  const labels = ["Node.js setup", "Bundler installation", "dependency installation", ...(rails ? [`${db.label} test database initialization`] : []), "Ruby version attestation"];
+  const labels = ["Node.js setup", "Bundler installation", "dependency installation", ...(rails ? [`${db.label} test database initialization`] : []), "Ruby version attestation", "Bundler version attestation"];
   const commands = [
     ["exec", runtime.appContainer, "sh", "-c", NODE_INSTALL],
-    ["exec", runtime.appContainer, "gem", "install", "bundler", "-v", "2.4.22", "--no-document"],
-    ["exec", runtime.appContainer, "bundle", "_2.4.22_", "install"],
+    ["exec", runtime.appContainer, "gem", "install", "bundler", "-v", runtime.bundlerToInstall ?? "2.4.22", "--no-document"],
+    ["exec", runtime.appContainer, "bundle", `_${runtime.bundlerToInstall ?? "2.4.22"}_`, "install"],
     ...(rails ? [db.createArgs({ appContainer: runtime.appContainer, databaseContainer: runtime.databaseContainer })] : []),
-    ["exec", runtime.appContainer, "ruby", "--version"]
+    ["exec", runtime.appContainer, "ruby", "--version"],
+    // Attest the Bundler version actually installed, so the report can warn when
+    // CI/host bundler differs. `gem install` output is advisory; `--version` is
+    // authoritative for what `bundle exec` will actually resolve.
+    ["exec", runtime.appContainer, "bundle", `_${runtime.bundlerToInstall ?? "2.4.22"}_`, "--version"]
   ];
   const results = commands.map((args, index) => {
     const result = docker(spawn, args);
     if (result.status !== 0) throw new Error(`Target runtime bootstrap failed during ${labels[index]}. Rerun prepare-target-runtime --ruby <x.y.z>.`);
     return result;
   });
-  const rubyOutput = `${results.at(-1).stdout ?? ""}${results.at(-1).stderr ?? ""}`;
+  // Index the attestations explicitly rather than from the end of the array:
+  // `ruby --version` is no longer the final command, and an off-by-one here would
+  // validate the Bundler banner against the Ruby regex.
+  const rubyIndex = 3 + (rails ? 1 : 0);
+  const rubyOutput = `${results[rubyIndex].stdout ?? ""}${results[rubyIndex].stderr ?? ""}`;
   if (!new RegExp(`^ruby ${runtime.ruby.replaceAll(".", "\\.")}(?:p\\d+|\\s|$)`).test(rubyOutput.trim())) throw new Error("Target runtime did not execute the requested Ruby version.");
   return {
     node: preparationResult(results[0]),
     bundler: preparationResult(results[1]),
     bundleInstall: preparationResult(results[2]),
     ...(rails ? { databaseCreate: preparationResult(results[3]) } : {}),
-    rubyVersion: preparationResult(results.at(-1))
+    rubyVersion: preparationResult(results[rubyIndex]),
+    bundlerVersion: `${results.at(-1).stdout ?? ""}${results.at(-1).stderr ?? ""}`.trim()
   };
 }
 function railsProject(root) {
@@ -164,7 +173,9 @@ export function prepareTargetRuntime({ root = process.cwd(), reportPath, ruby, d
   const canonical = canonicalRoot(root);
   const db = resolveDatabase(database ?? detectDatabase(canonical));
   const selected = selectedRun(canonical, reportPath);
-  const runtime = { version: 2, runId: selected.run.runId, reportPath: selected.reportPath, ruby, database: db.adapter, ...names(selected.run.runId, db) };
+  const run = readRun(canonical, selected.reportPath);
+  const bundlerToInstall = run.reportType === "bundler_bridge" ? run.targetBundler : (run.bundlerBridge ? run.bundlerBridge.bundlerTo : undefined) || "2.4.22";
+  const runtime = { version: 2, runId: selected.run.runId, reportPath: selected.reportPath, ruby, database: db.adapter, bundlerToInstall, ...names(selected.run.runId, db) };
   const owner = identity(runtime.runId, canonical);
   const existing = readTargetRuntime(canonical);
   if (existing && existing.runId !== runtime.runId) {
@@ -250,5 +261,10 @@ export function validateTargetRuntime({ root = process.cwd(), runtime = readTarg
   const expectedIds = [app?.Id, database?.Id].sort();
   const valid = appMatches(app, canonical, runtime, db) && databaseMatches(database, runtime, db) && hasOwnership(network, owner) && hasOwnership(app, owner) && hasOwnership(database, owner) && connectedIds.length === 2 && connectedIds.every((id, index) => id === expectedIds[index]) && app?.Image === runtime.resolvedImageId && (!runtime.databaseImageId || database?.Image === runtime.databaseImageId) && env.RAILS_ENV === "test" && env.DATABASE_URL === db.databaseUrl(runtime.databaseContainer);
   if (!valid) throw new Error("Target runtime no longer matches its prepared run. Rerun prepare-target-runtime --ruby <x.y.z>.");
-  return { runId: runtime.runId, reportPath: runtime.reportPath, name: runtime.appContainer, id: app.Id, imageId: app.Image, imageRef: app.Config.Image, ruby: runtime.ruby, database: runtime.database, databaseContainer: runtime.databaseContainer, databaseContainerId: database.Id, databaseImageId: database.Image, databaseImageRef: database.Config.Image, network: runtime.network, networkId: network.Id };
+  // bundlerVersion is surfaced so the generated report can warn that the deploy
+  // host and CI may resolve a different Bundler than this container pinned. It
+  // comes from `bundle --version` in the prepared container, not from the
+  // bootstrap log, so it reflects what `bundle exec` actually resolved.
+  const bundlerVersion = /Bundler version (\d+(?:\.\d+)+)/.exec(runtime.preparation?.bundlerVersion ?? "")?.[1] ?? undefined;
+  return { runId: runtime.runId, reportPath: runtime.reportPath, name: runtime.appContainer, id: app.Id, imageId: app.Image, imageRef: app.Config.Image, ruby: runtime.ruby, ...(bundlerVersion ? { bundlerVersion } : {}), database: runtime.database, databaseContainer: runtime.databaseContainer, databaseContainerId: database.Id, databaseImageId: database.Image, databaseImageRef: database.Config.Image, network: runtime.network, networkId: network.Id };
 }