ruby-gc

name	ruby-gc
description	Audit asdf-installed Ruby versions against project pins and remove unreferenced ones. Dry-run by default.
disable-model-invocation	true
argument-hint	[--apply]

Ruby GC

Garbage-collect asdf-installed Ruby versions that nothing on the system references.

Dry-run by default. Without --apply, this is a read-only report and you must not uninstall anything.

Arguments

• $ARGUMENTS — pass --apply to enable the uninstall step. Absent that flag, stop after the report.
• --apply enables deletion; it does not authorize it. You still show the full table and get an explicit yes first.

Safety rules

These are non-negotiable. The cost of a wrong delete is a broken app plus a slow rebuild; the cost of a wrong keep is a few hundred MB.

1. Never delete the global version — the one in ~/.tool-versions.
2. Never delete a version that has any pin on disk, wherever that pin lives.
3. Never delete without showing the table and getting an explicit confirmation in the same session.
4. If the scan errors, or returns implausibly few pins, STOP and report. A truncated scan is indistinguishable from "nothing uses this" — it produces a confident delete list that breaks real apps. This has happened; treat a thin result as a bug in the scan, not a licence to delete. "Implausibly few" is measured against the July 2026 baseline in "Calibration" below — check it every run, before classifying anything.
5. Uninstall one version at a time, reporting each result before the next.

Your task

1. Inventory what's installed

asdf list ruby
du -sh ~/.asdf/installs/ruby/*

2. Read the global pin

cat ~/.tool-versions

This is a symlink into ~/dotfiles/asdf/.tool-versions (the real dotfiles). Note that ~/code/my_repos/dotfiles/ and ~/dotfiles.bak/ are stale clones carrying outdated pins — ignore them as authorities on the global version, though their pins still count under rule 2 until the user cleans them up.

3. Scan for pins — FULL DEPTH

find ~ -type f \( -name .tool-versions -o -name .ruby-version \) \
  -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/Library/*' -not -path '*/.Trash/*' \
  -not -path '*/vendor/*' -not -path '*/.asdf/*' \
  -not -path '*/.local/share/nvim/*' -not -path '*/.local/share/zap/*' \
  -not -path '*/.local/share/neobean/*' \
  -exec grep -H . {} + 2>/dev/null

Do not add -maxdepth. Projects nest deeper than seems reasonable — code/active/eto/ComixDistroBase/comix_distro/ is five levels below ~/code, and a -maxdepth 4 scan silently misses it while still returning plenty of plausible-looking output.

Scan all of ~, not just ~/code. Real projects live in ~/Sites/ too — that's where the legacy ETO sites pinning Ruby 2.7.4 are.

The plugin-directory exclusions are deliberate: nvim and zsh plugins vendor their own .tool-versions (bullets.vim pins ruby 3.1.0, neotest-rspec pins 3.1.1, a zap plugin pins 2.5.3). Those are library artifacts, not projects, and shouldn't hold an install hostage.

3b. Scan Gemfiles too — they are live pins

~/dotfiles/asdf/.asdfrc sets legacy_version_file = yes, and asdf-ruby's bin/list-legacy-filenames echoes .ruby-version Gemfile. So a Gemfile is a version pin on this system, exactly like a .ruby-version. Verify both facts each run rather than trusting this note — if legacy_version_file is ever turned off, Gemfiles stop counting.

find ~ -type f -name Gemfile \
  -not -path '*/node_modules/*' -not -path '*/.git/*' \
  -not -path '*/Library/*' -not -path '*/.Trash/*' \
  -not -path '*/vendor/*' -not -path '*/.asdf/*' \
  -not -path '*/.local/share/*' \
  -exec grep -HE '^\s*ruby\s' {} + 2>/dev/null

3c. Calibration — is this scan plausible?

Rule 4 is only enforceable against a known-good baseline. Measured 2026-07-17, immediately after a cleanup run:

Signal	Baseline	Treat as a broken scan if...
.ruby-version + .tool-versions files found	58	fewer than ~40
.tool-versions carrying a ruby line	21	fewer than ~14
Gemfiles with any ruby line	113	fewer than ~80
Gemfiles with an exact ruby pin	10	zero

Counts drift as projects come and go, so treat them as an order-of-magnitude check, not an assertion — a 20% wobble is normal, a 60% drop is a bug. The landmark checks below are the real test, because they fail loudly rather than plausibly:

• The scan MUST reach ~/Sites/ — 13 ruby pins live there, including the legacy ETO sites on 2.7.4. Zero hits under ~/Sites means the scan never left ~/code.
• The scan MUST reach ~/code/active/eto/ComixDistroBase/comix_distro/. Missing it means a depth limit crept in.
• The deepest real pin sits 9 levels below ~ (~/code/active/eto/ETOWebReboot/legacy/*/.tool-versions). Any -maxdepth silently truncates this.

Note the Gemfile ratio: 113 files carry a ruby line but only 10 are real pins. That gap is the ~100 prag-studio Gemfiles pinning ruby '>= 3.0.0'. If exact pins ever approach the total, the parse is wrongly counting range specifiers — that inflates the keep list and makes the skill useless rather than dangerous. Both failure directions are worth catching.

4. Parse the pins carefully

Five formats, all present on this system:

File	Example contents	Extract
.ruby-version	ruby-4.0.6	strip the ruby- prefix → 4.0.6
.ruby-version	3.1.2	use as-is
.tool-versions	ruby 3.1.2	the ruby line only — the file also carries nodejs, python, lua, neovim
Gemfile	ruby "3.1.2"	→ 3.1.2 — a real pin
Gemfile	ruby '>= 3.0.0' or ruby file: ".ruby-version"	not a pin — ignore

A .tool-versions line may list multiple fallback versions (python 3.12.4 2.7.18); if a ruby line ever does, every version listed counts as pinned.

Only an exact Gemfile version pins anything. parse-legacy-file's sed pipeline ends with /^[^0-9]/d, which drops any result not starting with a digit — so >= 3.0.0 yields nothing, and file: ".ruby-version" defers to the .ruby-version already scanned in step 3. This matters: ~100 prag-studio Gemfiles say ruby '>= 3.0.0', and counting them would wrongly pin versions nothing uses. Mirror the plugin's real behavior; don't invent stricter or looser rules.

5. Classify each installed version

• Global → keep, always.
• Has ≥1 pin → keep. Record which paths, so the report can show its reasons.
• Zero pins → delete candidate.

Sort delete candidates into two tiers, and present them separately:

• Unreferenced — no pin anywhere. Safe.
• Judgment — pinned only by archived clones (~/code/archives/), throwaway sandboxes (~/code/rails/, ~/code/fly/), other people's dotfiles (~/code/nathan/, ~/code/kelsie/), or stale dotfile copies. Technically pinned, plausibly disposable — the user decides, per version, every run. Never fold these into the safe tier.

6. Report

Show a table: version, size, keep/delete, and the concrete reason (a pin path, or "no pins found"). Include the total reclaimable.

Also report pins referencing versions that aren't installed (e.g. 3.3.4 has pins but no install). It means those projects are already broken, and it's a useful signal that a pin doesn't prove a project is alive.

State the known gaps every run, so the user can calibrate:

• Only ~ is scanned — anything on an external volume is invisible.
• Pins are read from .ruby-version, .tool-versions, and Gemfile. A project selecting its Ruby some other way (a wrapper script, a Docker image, direnv) would not show up.

CHECKPOINT: stop here unless --apply was passed. Report and end.

7. Uninstall (only with --apply + explicit confirmation)

Confirm the exact list with the user, then per version:

asdf uninstall ruby <version>

Report each result. Afterwards, re-run asdf list ruby and du -sh ~/.asdf/installs/ruby to show the new state and actual space reclaimed.

Relationship to /create-bump

/create-bump is a project-local skill in the asdf working repo (~/code/active/asdf/.claude/skills/create-bump/), not part of dotfiles — it won't appear in this repo.

It uninstalls only the single MRI version it installed for testing — safe, because it created that version minutes earlier and nothing can be pinned to it yet. It must not call this skill or do fleet-wide cleanup; a routine ruby-build bump should never be able to delete an app's Ruby. Run /ruby-gc deliberately, on its own.

That constraint is enforced where it binds — in /create-bump's own step 8, since a skill can only follow rules written in the file it reads. The note here is orientation, not enforcement. If /create-bump is ever rewritten, re-check that its step 8 still carries the no-fleet-cleanup rule.