Add a REFERENCE.md freshness check to pr_tests.yml and roll it out fleet-wide

[hcaballero2]

Closes #46. Also reconciles the pr_tests.yml template with the deployed fleet (#41).

This started as @hcaballero2's freshness check (the first four commits, rebased onto main) and grew into the full rollout package, following our convention of combining the template change and the workflow run in one PR so they're tested together:

1. Reconcile the pr_tests.yml template with the deployed fleet — the template was behind the workflows actually deployed (checkout@v7, Ruby 3.2/3.4, the enabled Ruby Style job, the OpenVox spec matrix, parallel_spec, and the acceptance job). The template now matches the fleet, with one difference: the reference job's step is bundle exec rake validate:strings (this PR's freshness check) instead of the deployed regenerate-and-diff block.

2. preserve_blocks for merge_gha_workflows — acceptance jobs are per-repo territory (simplib and x2go run custom docker matrices), so the merge task can now be told to keep whole blocks from the existing file (preserve_blocks: [jobs.acceptance]). Blocks are spliced by Psych node line spans before the scalar-grafting pass, so template comments/formatting still can't be disturbed. Repos without their own acceptance job get the template's vagrant-based one.

3. Rewrite the generate_reference_md task — the 2023-era task self-committed, took a metadata.json path it only used to find the repo, and had a NameError on non-simp gems. It now takes repo_path, runs bundle install + bundle exec rake strings:generate:reference (gems shared across repos via .vendor/bundle), reports {changed}, and leaves committing to the git_commit_changes stage. The plan stage filters to project_type == pupmod.

4. Session config 20260811-reference-md.yaml (now latest) — merges pr_tests.yml (scoped, with preserve_blocks: [jobs.acceptance]) and regenerates every module's REFERENCE.md so the new check starts green fleet-wide.

Verified:

• 211 plain rspec examples + 18 BoltSpec plan examples, all green (new specs cover block preservation/insertion/idempotency and the rewritten task via a faked BUNDLER_EXE)
• ci-managed-file-contract.sh passes; all plans parse and load
• Local e2e against real clones of pupmod-simp-aide and pupmod-simp-simplib: aide's diff is exactly the reference-step swap, simplib gets the new reference job with its custom acceptance matrix untouched, and both repos' REFERENCE.md regenerated with no drift

🤖 Generated with Claude Code

---

Update after the first fleet run (72 PRs): two defects surfaced and are fixed here:

• 9 repos gained the template's acceptance job despite having none — 5 of them (simp_banners, simp_options, site, tuned, vnc) have no spec/acceptance suites at all, so the job could only fail (example: [puppetsync] Add a REFERENCE.md freshness check to PR tests pupmod-simp-simp_options#134). preserve_blocks is now repo-authoritative in every direction: the template's block is removed when the repo has none, so a repo only gets an acceptance job by adding one itself.
• rubygem-simp-compliance_engine was classified as a pupmod (it carries a pupmod-shaped metadata.json alongside its gemspec) and its fully custom pr_tests.yml was flattened into the module template. Gemspec detection now runs before pupmod detection, so gems stay out of module-template syncs. Its PR was closed.

Remediation: just re-run bolt plan run puppetsync from this branch. The 63 correct repos come out unchanged (their feature branches already match, so the GitHub stages skip them); the 8 affected repos rebuild from master and force-push corrected branches over their open PRs; compliance_engine is filtered out by the classifier fix. Verified locally against real clones of simp_options (reference job added, no acceptance job, REFERENCE.md regenerated) and compliance_engine (rejected as rubygem).