docs: make v2.2.0 the single current-release source of truth #567

Goal

Make v2.2.0 the single current-release source of truth across the upstream onboarding documentation and its documentation gate, so a new user following the demo cannot be sent to a stale v2.1.0 install or verification path.

Background

The published baseline is base-bash-libs v2.2.0 at commit d8894bf4453e6b6beaa6de7ce2e082497cb236f2 (published 2026-10-07). The top of README.md already presents v2.2.0, and base-bash-libs-demo links to the v2.2.0 documentation tag. However, the same upstream checkout still contains conflicting current-release instructions:

• README.md lines 156-165 pin the source-checkout example to the v2.1.0 commit, while lines 240-246 call v2.1.0 the current stable release.
• docs/v2/quickstart.md lines 9-19 instruct a new consumer to install v2.1.0 at 36fec50c....
• docs/versioning-policy.md lines 5, 14, 63-65, and 128-138 describe v2.1.0 as current and use its release commands and commit.
• docs/pinned-consumption.md lines 30-34 identify v2.1.0 as the canonical asset set.
• docs/consumer-validation-status.md lines 26-31 still call v2.1.0 the current supported canary release.
• tests/docs-contract.sh lines 27-45 assert the v2.1.0 reference and therefore passes while the user-facing docs are inconsistent with the published v2.2.0 release.

This is especially confusing because the demo's README and docs index correctly point newcomers to v2.2.0 versioned upstream pages. The linked quickstart then sends them to a different release line.

Scope

• Update all unqualified current-release, stable-release, quickstart, pinned-consumption, release-command, and supported-canary references to v2.2.0 and its verified full commit.
• Preserve v2.0.0/v2.1.0 references that are historical or compatibility baselines, but label them explicitly as such.
• Make the docs contract derive its expected current version and commit from the repository release metadata, or otherwise fail closed when user-facing current-release claims drift from VERSION and the published tag.
• Reconcile the versioned v2.2.0 documentation that base-bash-libs-demo links to, including the quickstart and pinned-consumption examples.

Acceptance Criteria

• A new user following the root README, docs/README.md, docs/v2/quickstart.md, docs/versioning-policy.md, and docs/pinned-consumption.md receives one coherent v2.2.0 install and verification path.
• The source-checkout and release-asset examples use the exact v2.2.0 commit and canonical v2.2.0 asset names.
• Historical compatibility rows and preview-module introduction notes remain accurate and are visibly historical rather than presented as the current release.
• The documentation contract fails for a deliberately stale current-release reference and passes for the v2.2.0 tree.
• The downstream demo's documentation contracts and runnable tutorial continue to pass against the corrected v2.2.0 pages.

Validation

• ./tests/docs-contract.sh
• ./tests/validate.sh
• git grep/a focused documentation scan for unqualified current-release claims and v2.1.0 pins
• In base-bash-libs-demo: ./tests/docs-contracts.sh, ./tests/docs-examples.sh, and ./scripts/verify-vendor

Non-Goals

• Do not change the v2 API or release artifacts.
• Do not rewrite historical v2.0.0 or v2.1.0 evidence.
• Do not change the demo's committed dependency pin as part of this documentation repair.

Project Fields

• Status: Ready
• Priority: P1
• Area: Docs
• Initiative: Adoption Polish
• Size: M

Agent Assignment

• Assignee: @codeforester