Freeze v5 support matrix and migration policy (#1156)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Fixes #1156

Summary

Freezes the v5 support matrix and migration policy in the docs, as the maintainer's 2026-10-09 triage comment on #1156 asks. Docs only. No behavior changes and no format is dropped or refused.

• docs/ecosystems.md gets a new v5 support tiers section (after the mode × ecosystem matrix):
  • Tier definitions: Supported, Beta, Legacy, Not supported.
  • A per-ecosystem × mode tier table.
  • Hosted JVM: hosted and vendored Maven/Gradle (and sbt/Mill/scala-cli) are Beta. The section names the open rewriter gaps (multi-module, <classifier>, profiles/plugins/comments, ${property}, imported BOMs, mirrors), links the pm:maven/pm:gradle issue lists, and says to run the build before trusting a JVM --vex. Agent-mode JVM stays Supported with its existing caveats.
  • Legacy: binary bun.lockb (hosted and vendored), vendored pnpm 7/8 locks (5.4/6.0), and vlt eras A0–B. Each keeps full read/write in v5 and gets an upgrade path and an undo path table. Hosted bun.lockb undo is the existing git checkout -- bun.lockb refusal.
  • A support policy:
    • v5.x never removes a format or makes one refuse that v5.0 accepts.
    • A tier can move up at any time. A move down is announced.
    • Removing a Legacy writer needs a major release, becomes a refusal with a re-lock remedy, and keeps list/vex/rollback reading the format.
• docs/migrating-to-v5.md gets a short Support tiers section that summarizes the above and links to it.

Root cause

The matrix listed what each mode handles, but not how mature that support is. Hosted JVM coverage and the retired-by-upstream lock formats had no stated tier or deprecation policy.

Facts checked against the code and tracker

• pnpm vendored accepts lockfileVersion 5.4/6.0/9.0 only (formats/pnpm/mod.rs sniff_lock_grammar), so pnpm 1–6 vendored is "Not supported".
• The vlt era table and the A0 vendored refusal come from the existing vlt notes.
• The hosted bun.lockb rollback refusal comes from docs/testing/bun-compatibility.md.
• JVM gaps: open issues Hosted Maven rewriter edits commented-out, plugin and profile markup, so builds either stay unpatched or break #259, Hosted Maven mode edits only the root pom of a multi-module build, leaves child literals unpatched, and still attests VEX #261, Hosted Maven rewriter ignores <classifier> and suffixes sources/tests/native classifier dependencies, which breaks the build #262, Maven hosted scan pins, and VEX attests, artifacts the project doesn't depend on (the crawler lists all of ~/.m2) #265, Maven pom rewrites add a second <repositories> or <dependencyManagement> section when the existing one is self-closed or has a comment before <dependencies>, so Maven refuses the pom #342, Vendored Maven reactor pins over an imported BOM or external parent, so a build that uses 1.11.0 is silently downgraded to 1.10.0-socket.* and a later BOM bump never takes effect #488 (v5-blocker) and Vendored JVM fetches upstream artifacts and checksums only from Maven Central, ignoring the build's mirrors and repositories #1069, Vendored Maven reactor ignores profile <properties>, so a version an active profile raises is silently downgraded to the patched base (1.11.0 → 1.10.0-socket.*) with exit 0 and no warning #459 and others (p3).

Checklist

• Decide: support tiers for bun.lockb writes, vendored pnpm 7/8 locks, vlt pre-1.0 locks and hosted Maven/Gradle #1156: tier table plus Beta label for hosted JVM; Legacy plus upgrade/undo paths for bun.lockb, vendored pnpm 7/8 and vlt pre-1.0; migration guide section. No code or behavior change.

No CHANGELOG edit (AGENTS.md).

🤖 Generated with Claude Code

---

Note

Low Risk
Documentation-only; no runtime, lockfile, or refusal behavior changes.

Overview
Documents the v5 support maturity model and release policy without changing CLI behavior. docs/ecosystems.md adds a v5 support tiers block after the mode matrix: tier definitions (Supported / Beta / Legacy / Not supported), an ecosystem×mode tier table, explicit Beta labeling for hosted and vendored Maven/Gradle (plus sbt/Mill/scala-cli) with rewriter-gap context and issue links, Legacy upgrade/undo paths for bun.lockb, vendored pnpm 7/8 locks, and pre-1.0 vlt locks, and a support policy (no format removal in v5.x minors/patches; tier moves; Legacy write removal only on major).

docs/migrating-to-v5.md adds a short Support tiers section that summarizes Beta/Legacy expectations and links to the ecosystems page.

^{Reviewed by Cursor Bugbot for commit 396aed0. Configure here.}

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 396aed0. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[final reviewer] I disarmed auto-merge at 396aed0a because ci-ok is red on this head. Only hosted-e2e and e2e (ubuntu-latest, e2e_safety_pnpm) fail, which is the main-wide minimist@1.2.2 failure (#1293), not this PR. #1302 fixes it and is in the merge queue now. Once main carries it, merge main in here (no other commits needed) and I'll re-arm auto-merge after CI goes green. The approval still covers this head.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Ready for review at eec8e061f480.

• CI: required checks ci-ok and clippy green; 5 check suites succeeded. 1 superseded workflow run(s) show as cancelled; the required gates passed on this head.
• Mergeable against main, no CHANGELOG.md change.
• Bugbot reviewed this head; no unresolved review threads.

Labeled Ready for review by the burn-down agent. Slack announcement pending (connector unavailable this run).

---

Generated by Claude Code