docs: align release validation gate contracts

[SSobol77]

Summary

Align current ECLI documentation, Makefile help, and regression tests with the
three-layer release validation architecture introduced by PR #142 and PR #143.

Validation layers

The repository now consistently distinguishes:

1. make validate-gate2

   • source and structural contract validation;
   • does not require built release artifacts or final release tooling.

2. make validate-built-artifacts

   • explicit physical artifact validation;
   • complete artifact/sidecar pairs are validated;
   • partial sets fail closed;
   • absent optional artifact pairs are skipped.

3. make validate-release-assets

   • verifies the exact final GitHub Release asset set;
   • preserves the exact 21 uploaded ECLI-owned asset contract.

What changed

• corrected the stale contributor documentation that associated twine and
  final PyPI artifact validation with validate-gate2;
• documented that twine is release-only tooling used by final PyPI
  built-artifact validation;
• clarified validation tooling prerequisites in the release process;
• added distinct Makefile help entries for all three validation layers;
• added regression tests for current normative documentation and Makefile help;
• preserved historical Gate 2 reports without rewriting past behavior.

Makefile help

The canonical help output now includes:

make validate-gate2           Source and structural contract gate
make validate-built-artifacts Validate available built artifacts fail-closed
make validate-release-assets  Verify exact final GitHub Release asset set

Each entry appears exactly once in both make help and make help-full.

Preserved contracts

This PR does not change:

• release workflow logic;
• job dependencies or publication conditions;
• artifact assembly;
• checksum generation or verification;
• the exact 21 GitHub Release asset contract;
• non-uploaded .checksums/ evidence;
• artifact names;
• versions;
• package mappings;
• runtime, UI, F4, TextMate, diagnostics, or providers.

Validation

Passed:

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run python scripts/check_runtime_imports.py
uv run pytest -q tests/docs
uv run pytest -q tests/packaging
uv run python scripts/f4_linter_linux_provisioning.py --check-official-evidence-drift
make validate-gate2
make help
make help-full
git diff --check

Observed:

tests/docs: 23 passed
tests/packaging: 532 passed
PASS: Linux official distro evidence drift audit clean

Scope

Changed only:

• Makefile
• docs/contributor/development-setup.md
• docs/release/release-process.md
• tests/docs/test_release_gate_contract_alignment.py
• tests/packaging/test_release_asset_count_gate.py

Summary by CodeRabbit

• Documentation

  • Clarified the three release validation layers: source checks, built-artifact checks, and final release asset verification.
  • Updated guidance for release-only tooling and checksum sidecar validation.
  • Improved Makefile help text for release validation commands.

• Tests

  • Added coverage to verify documentation alignment, validation-layer distinctions, and release asset/checksum requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9fa3c6b9-7bfb-49a5-94a2-a4c1e01f238d

📥 Commits

Reviewing files that changed from the base of the PR and between 66b6f94 and 0205c75.

📒 Files selected for processing (5)

• Makefile
• docs/contributor/development-setup.md
• docs/release/release-process.md
• tests/docs/test_release_gate_contract_alignment.py
• tests/packaging/test_release_asset_count_gate.py

---

📝 Walkthrough

Walkthrough

The changes align Makefile help text, contributor documentation, release procedures, and tests around three distinct release validation layers: source contracts, built artifacts, and final release assets.

Changes

Release validation contract

Layer / File(s)	Summary
Validation command surface Makefile, tests/packaging/test_release_asset_count_gate.py	The help output now presents validate-gate2, validate-built-artifacts, and validate-release-assets as distinct commands, with tests checking their presence and descriptions.
Validation documentation and contracts docs/contributor/development-setup.md, docs/release/release-process.md, tests/docs/test_release_gate_contract_alignment.py	Documentation separates source, built-artifact, and final release-asset validation, defines twine as release-only tooling, and adds tests for the documented contracts and historical Gate 2 references.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: aligning release validation gate contracts across docs, Makefile help, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/release-gate-contract-alignment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud