Fixtures follow-through for dependency renames: .fixtures.yml must gain a successor's new deps or specs fail

Problem

When update_metadata_deps (#68 / PR #93) renames a superseded dependency in metadata.json, the successor module can carry new dependencies of its own. Unless those are added to .fixtures.yml, rake spec_prep won't install them and the module's compile-with-all-deps specs fail — i.e. the very sync PR that performs the rename goes red. The rename path and the fixtures update are coupled and must land in the same session.

This is not urgent today: a fleet scan (2026-08-24) of all 75 unique dependency slugs across the 70 pupmod repos found zero superseded and zero deprecated modules — the herculesteam→puppet era migrations are fully absorbed, and the current metadata refresh round is range-bumps only. But the next upstream supersede will hit this.

Prior art

silug/puppet-tools update-fixtures already solves the general problem: it inventories installed fixtures, resolves supersedes via the Forge, walks Forge modules' own dependency metadata for the transitive closure, adds missing modules as forge_modules, and prunes entries nothing needs.

Proposed design — two modes, one resolver

Extract the Forge resolution logic from update_metadata_deps into a shared files/forge_resolver.rb (like github_pr_forker.rb), then:

1. Rename-triggered fixtures repair (stateless, belongs in the metadata sync). When update_metadata_deps renames a dep, ensure .fixtures.yml covers the successor and its transitive dependencies — all derivable from the Forge API (current_release.metadata.dependencies), checked against the fixture keys already declared in .fixtures.yml (repositories + forge_modules short names). No local fixture state needed. Existing forge_modules values matching the old slug are updated; repositories git-URL entries (simp forks) are left alone with a warning — whether to retarget a fork is a human decision.
2. Full closure reconciliation (stateful, its own session — the update-fixtures port). The complete inventory/add/prune pass, which requires per-repo bundle install + rake spec_prep to know what installed fixtures transitively provide. Heavyweight (generate_reference_md-class runtime) and worth its own validation round.

Both modes need comment-preserving output: .fixtures.yml files carry meaningful comments (e.g. aide's explanation of why compliance_engine is a fixture but not a dependency), so full to_yaml round-trips are out. Targeted Psych-node-span line edits (the merge_gha_workflows technique) fit: update a value in place, insert new entries after the last child of forge_modules, create the section if absent.

Sequencing

Mode 1 should land before (or with) the first sync that performs a real rename; it's a natural extension of update_metadata_deps. Mode 2 replaces the one-off modernize_fixtures task and can follow at leisure.

Start by reading update_metadata_deps and the existing update-fixtures script, then compare their Forge resolution responsibilities. Review .fixtures.yml structure and the comment-preserving merge_gha_workflows technique before designing files/forge_resolver.rb. Done means rename-triggered fixture repair covers successor dependencies without losing comments, and rake spec_prep passes the compile-with-all-deps specs.