docs: record the invariants path list as permanent compatibility

[loadinglucian]

Summary

PR #24 restored the invariants path fallback after it turned out to be load-bearing, but left a docstring promising its removal once a commit touching support-policy.json landed after the rename. That removal condition is wrong, so this replaces it.

support-policy.json carries policyInvariantsDigest, and consumer.py rejects a capture where the captured policy does not match the captured invariants. The two documents only agree inside the tree php-bin reviewed them in, which is exactly why the capture pins to the commit that last changed the policy: at that commit php-bin's own validation had just checked one against the other.

That makes the pin correct rather than under-specified, and rules out the obvious alternatives:

• Pinning to whichever of the two documents changed last would pair new invariants with a policy still carrying the previous digest, and the capture would fail on every invariants-only change.
• Advancing the pin with a fresh support-policy.json commit would need a real edit, but every field in that file is a semantic claim and its digest already matches. There is no honest change to make, and an empty commit is not one.

So the pinned commit can be arbitrarily old, and the invariants path is whatever php-bin's layout was at the time. The two-URL list is permanent compatibility with historical layouts rather than a pending cleanup, and the next path move should extend it. The docstring now says that and explains why the alternatives do not work, so the reasoning sits with the code.

Docstring and one test comment only. No executable change.

Verification

• scripts/test.sh
• Unsupported-target behavior remains explicit
• Release selection and checksum behavior are covered by tests
• The php-bin release contract remains compatible

scripts/test.sh passes locally at 9 tests plus the plugin contract, and Plugin contract is green on this PR. The remaining three items are unaffected by construction: the diff changes a docstring and a comment, so no target check, release selection, checksum path, or contract surface is touched. git diff on this branch is confined to the docstring body in fetch_first_url and two comment lines in test/test_autorelease.py.

Security

• Downloads still require an exact SHA-256 entry
• No credentials, generated fixtures, or install directories are committed

Both hold for the same reason: there is no executable change. The checksum requirement lives in the install path, which this PR does not touch, and the diff adds no files.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_5c60117d-00c0-469e-a906-a53211ff9ce4)

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request updates fetch_first_url documentation and a related test comment. It documents historical php-bin path compatibility, newest-first lookup, and fallback only on 404. No executable logic changes.

Changes

Policy path documentation

Layer / File(s)	Summary
Document fallback behavior autorelease/consumer.py, test/test_autorelease.py	The documentation describes commit-pinned captures, historical path compatibility, newest-first lookup, and 404-only fallback. The test comment describes historical php-bin layouts.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Possibly related PRs

• Bigpixelrocket/mise-php#21: Documents the same autorelease/consumer.py fallback behavior and historical php-bin layout.
• Bigpixelrocket/mise-php#23: Modifies documentation for fetch_first_url and historical policy-path fallback behavior.
• Bigpixelrocket/mise-php#24: Implements the documented pinned-policy fallback behavior referenced by this change.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
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.
Title check	✅ Passed	The title clearly and concisely describes the documentation change that establishes permanent compatibility for the invariants path list.
Description check	✅ Passed	The description includes complete Summary, Verification, and Security sections with relevant rationale, test results, and checked requirements.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/permanent-invariants-path-compat

---

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

[loadinglucian]

Thanks, both pre-merge warnings checked. One was a real miss, one I am declining with reasons.

Description check: valid, fixed. You were right. .github/pull_request_template.md does require Verification and Security sections and I wrote a prose description instead of following it. The description now follows the template. I filled in the boxes honestly rather than just ticking them: scripts/test.sh passes locally at 9 tests plus the plugin contract, and the remaining items are unaffected by construction because the diff is a docstring body and two comment lines with no executable change. Good catch, and it applies to a few other PRs I opened in this batch too.

Docstring Coverage: declining, and I think the 50% is measuring something narrower than it looks. The figure comes from the two symbols this diff touches. fetch_first_url has a docstring, and test_policy_invariants_capture_prefers_the_current_path does not, so 1 of 2. The undocumented one is a test method, and this repo documents 0 of its 10 test methods, so adding a docstring to just this one would break local consistency rather than improve it. The test names already read as sentences, which is the convention here.

For the wider picture, autorelease/consumer.py sits at 2 of 16 documented and test/test_autorelease.py at 0 of 10. Both numbers are unchanged by this PR, since it edits an existing docstring rather than adding any symbol. Raising consumer.py to the 80% threshold means documenting about twelve unrelated functions in a protected path, which would turn a 14 line diff into something that needs its own review. Happy to do that as a follow-up PR if the owner wants it, but not folded into this one.

No inline findings this round, and the review at a3edb4f matches the current head, so nothing else is outstanding from your side.

[loadinglucian]

Review summary

Round complete. No inline comments and no formal reviews were filed. Both findings came from CodeRabbit's pre-merge checks.

Fixed (1)

• Description check. Valid, and a real miss on my part. .github/pull_request_template.md requires Verification and Security sections and I had written a prose description instead. The description now follows the template, with the boxes filled in with reasoning rather than ticked blank. CodeRabbit re-evaluated and this check now passes.

Declined (1)

• Docstring Coverage at 50%. The figure covers the two symbols this diff touches: fetch_first_url, which has a docstring, and test_policy_invariants_capture_prefers_the_current_path, which does not. The undocumented one is a test method, and this repo documents 0 of its 10 test methods, so adding one here would break a consistent convention rather than restore one. Measured with ast, the wider files sit at 2 of 16 for autorelease/consumer.py and 0 of 10 for test/test_autorelease.py, and both numbers are unchanged by this PR since it edits an existing docstring rather than adding a symbol. Bringing consumer.py to the 80% threshold means documenting about twelve unrelated functions in a protected path, which deserves its own review. Left unresolved so a human can weigh it.

Answered (0)

No human comments to respond to.

Check status

• Plugin contract: pass
• CodeRabbit: pass, no actionable comments
• Protected controls: fail, by design. autorelease/consumer.py is a protected path, so the job requires an exact-head approval from loadinglucian at a3edb4f3440d76e46d503a8a11e882d64685895a. This is the control working, not a defect, and it cannot be satisfied from the automation side.
• Cursor Bugbot and Cursor Security Agent: skipped. Bugbot reported "usage limit reached" rather than reviewing, so that reviewer's coverage is absent rather than clean.

Leaving this PR open. The merge decision and the exact-head approval are both the owner's.