[hellices]

Closes #481

Summary

The Relock workflow's propose job downloaded the verified uv.lock over its sparse checkout of main, then switched to the tested base revision with git checkout -b "$branch" "$BASE_SHA". When the base's uv.lock differs from main's, git refuses to carry that local change across:

error: Your local changes to the following files would be overwritten by checkout:
	uv.lock

Every relock onto such a branch therefore failed after all its verification. Runs 40155755520 and 40158406513 hit it on #482's branch, and both locks had to be committed by hand. Earlier runs all used base=main, whose tip is the tested revision, so the switch changed nothing.

• The fix: the artifact now downloads to $RUNNER_TEMP/relocked-lock, outside the checkout.
  • The host check (with main's validator) and the digest match run on it there, before the token is exposed, as before.
  • Only after the base revision is checked out is it copied in.
  • The file about to be staged is then matched to the digest once more, before git add --sparse uv.lock.
• Unchanged: the trust anchor (the validator still comes from main), the write-token boundary, and the branch-from-BASE_SHA rule.
• Docs: the Relock section of docs/dev/quality-gates.md now says the base can be any branch and describes the second digest match.

Verification

• The failure, reproduced: tests/test_lockfile.py::test_the_verified_lock_is_committed_onto_any_base runs the job's own steps against a temporary repository: a bare origin, a sparse checkout of main, the artifact placed where download-artifact puts it, and a stub gh. It is parametrized over three bases: main itself, a branch that shares main's lock, and a branch with its own lock. Before the change, the last case failed with CI's exact error and the first two passed, matching real runs.
• Now: all three push the verified bytes, and nothing else, onto the tested revision.
• The gh stub (after review) records each call's exact arguments and accepts only gh auth setup-git and gh pr create. The test asserts the whole call sequence, so a workflow that also ran gh pr merge would fail it, whether or not the call is guarded with || true. Both forms were checked by mutation. The pr create options must be exactly --base, --head, --title and --body, in that order, with the expected values, so an added --repo or a stray argument also fails the test.
• Second digest match: test_the_committed_bytes_are_the_bytes_that_were_verified now also pins it between the copy and git add. Removing that match, or moving it before the copy, fails the test with a message naming the problem.
• Mutation: putting the artifact back over the checkout fails the new test with CI's exact error.
• Platform: the new test is skipped on Windows, because the workflow runs only on Linux runners. Elsewhere it uses GNU sha256sum, falling back to shasum -a 256 (same options) where the system one is BSD's.
• zizmor: uvx zizmor .github/workflows/relock.yml reports no findings, with the same 4 suppressed as main's copy.

Run locally on macOS with Python 3.13 and the frozen lock. Each step ran directly with the project's environment rather than through make, because this machine cannot sync from PyPI:

Command	Result
pytest -p no:tach tests/test_lockfile.py tests/test_docs_links.py tests/test_docs_build_config.py tests/test_ci_workflow.py	161 passed
python scripts/check_source_size.py	passed
ruff check src/ tests/ and ruff format --check src/ tests/	passed; 659 files already formatted
SKIP=mypy,source-size pre-commit run --files <changed files>	passed
mypy	no issues in 659 source files
tach check	all modules validated
pytest -n 8 -q	13,758 passed, 25 skipped

The workflow itself only runs on dispatch. The next Relock run on a non-main base will be the first end-to-end use.

This PR's CI on the final head (6a63a41f, hosted runners, four xdist workers) passed every required check: pre-commit, security (including zizmor), dependency-review, analyze, and:

Job	Result
test (3.11)	passed, 13m11s
test (3.12)	passed, 16m52s
test (3.13)	passed, 13m44s
windows-test	passed, 11m19s (the new test is skipped there)

Checklist

• This closes an accepted issue in this repository that is assigned to me.
• Tests cover the change, written to fail first where behavior changed.
• make check passes locally.
• User-facing docs and the README match the change, or nothing user-facing changed.
• No security invariant is weakened: writes still need a keystroke approval
  and a fail-closed audit entry, and sensitive reads are still masked.

[Copilot]

🔵 Needs a closer look

Required CI completion remains unconfirmed for this write-enabled workflow change.

No open issues 🎉

What changed in this PR

Fixes #481 by allowing Relock to commit its verified lock onto a base branch whose uv.lock differs from main’s, without changing the existing validation or token boundaries.

Changes:

• Downloads the artifact outside the checkout, copies it after switching to the tested revision, and rechecks its digest before staging.
• Adds regression coverage for three base-branch scenarios and the copy/check/stage order.
• Documents support for arbitrary base branches and the second digest check.

File	Description
tests/​test_lockfile.py	Adds base-branch regression tests and digest-order assertions.
docs/​dev/​quality-gates.md	Explains artifact placement and validation before staging.
.github/​workflows/​relock.yml	Defers copying the verified lock until after checkout of the tested base.

_{Review effort: Balanced}

[my-reviewer-agent]

이슈 1건을 인라인 코멘트로 남겼습니다.

[Copilot]

🟢 Approval recommended

The focused fix addresses the checkout failure, preserves validation boundaries, and includes regression coverage with no unresolved findings.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

No blocking code issues were identified, but required test and analysis checks for the current head are still running.

No open issues 🎉

_{Review effort: Balanced}

[my-reviewer-agent]

이슈 1건을 인라인 코멘트로 남겼습니다.

[Copilot]

🔵 Needs a closer look

Required test and analysis checks on the current revision are still running, so the green-check prerequisite remains unconfirmed.

No open issues 🎉

_{Review effort: Balanced}

[my-reviewer-agent]

검토 범위에서 보고할 이슈가 없습니다.

[Copilot]

🟢 Approval recommended

The focused checkout-order fix preserves validation and credential isolation, with regression coverage for the affected scenarios and no unresolved findings.

No open issues 🎉

_{Review effort: Balanced}