docs(proposal): add release cooldown design for version resolution

[LalatenduMohanty]

Pull Request Description

What

Add a design proposal for release cooldown -- a configurable minimum release age for version resolution. The proposal introduces a --min-release-age CLI option (days, default 0) that makes fromager skip package versions published fewer than N days ago, with per-package overrides via resolver_dist.min_release_age in package settings.

Why

Supply-chain attacks often publish a malicious package version and rely on automated builds picking it up immediately. A cooldown window lets the community detect and report compromised releases before fromager consumes them.

See: #877

• PR follows CONTRIBUTING.md guidelines

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a new proposals documentation section and registers it in the main docs index. Introduces docs/proposals/index.rst as a landing page and docs/proposals/release-cooldown.md as a detailed proposal describing a configurable "release cooldown" feature: a global --min-release-age CLI option (and FROMAGER_MIN_RELEASE_AGE env var), per-package resolver_dist.min_release_age overrides, enforcement in provider candidate validation using a UTC start_time, required provider timestamp sources, a pre-built wheel exemption, and changes to list-versions / list-overrides reporting. No code or public API declarations are changed in this PR.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a design proposal document for a release cooldown feature for version resolution.
Description check	✅ Passed	The description is directly related to the changeset, explaining the what (design proposal for release cooldown), why (mitigate supply-chain attacks), and referencing the relevant issue.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/proposals/release-cooldown.md`:
- Around line 63-66: The click option for "--min-release-age" currently uses
click.IntRange(min=0) which rejects negatives instead of treating them as 0;
update the option definition for "--min-release-age" to either pass clamp=True
to click.IntRange (e.g., click.IntRange(min=0, clamp=True)) or add a
post-validation normalization for the parameter (e.g., in the command function
that accepts min_release_age, coerce min_release_age = max(0, min_release_age))
so negative inputs become 0; ensure you modify the decorator/option declaration
or the command handler that receives the min_release_age argument (look for the
click.option for "--min-release-age" and the command function parameter
min_release_age).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 3059b861-0da5-4cd5-90bf-907fc351cb54

📥 Commits

Reviewing files that changed from the base of the PR and between aec9c9c and 37b1f1e.

📒 Files selected for processing (3)

• docs/index.rst
• docs/proposals/index.rst
• docs/proposals/release-cooldown.md

[ryanpetrello]

note to reviewers:

I've taken another stab at a more full-featured solution to this problem over in #1018

(based on feedback from a number of you in this PR)