[Release/Docs] Align ADR 0003 build-backend pin with protected package authority

[seonghobae]

Protected-main release-evidence documentation defect — refreshed 2026-08-30

Protected main is exact b84f0c94154043a3473939c01bb6471de5a129ae.

At that exact tree, two protected release-evidence documents disagree with the executable package authority:

• docs/adr/0003-reproducible-release-evidence.md is exact blob 6740fbe8d3fb86ab4c2edfe88e5b4e80a4561e78, remains Status: Proposed, and specifies uv 0.12.3 with backend requirement uv_build==0.12.1 in both Context and Decision; and
• docs/doctoring/reproducible-release-evidence.md is exact blob eb91f782d93cf33c0fb9b379a695e8f009193943 and likewise tells operators that the governed path uses/requires uv_build==0.12.1, including its operator-verification and build-toolchain-failure instructions.

The same protected tree's pyproject.toml, exact blob 701c84e7cbff2e9942986c0d3f6e4b746cd48ddc, instead declares:

[build-system]
requires = ["uv_build==0.12.3"]
build-backend = "uv_build"

Thus the defect is broader than ADR 0003 alone: both the Proposed decision record and the protected operator doctoring contract are stale relative to the exact PEP 517 package authority. This is a bounded release/provenance documentation defect, not proof of package-build failure or wrong published artifacts. The ADR remains Proposed; do not invent an Accepted historical decision.

Exact executable evidence for the current protected package path

Release Acceptance run 32098143650 / job 95593334211 on unchanged #233 head 5951b7a4d779903b8924abaef2a387cae50b7f54 previously established exact-source reproducibility for the current protected package authority: exact checkout verification, CPython 3.14.7, uv 0.12.3, exact checked-out pyproject.toml requiring uv_build==0.12.3, two independent git archive source trees, two clean uv build --no-sources executions, byte-identical wheel/sdist identity, and bounded evidence named for the exact source commit.

Accordingly, the implemented package/reproducibility path represented by protected main@b84f0c9 is consistent with uv 0.12.3 + uv_build==0.12.3, while both ADR 0003 and the reproducibility doctoring note still name uv_build==0.12.1. Exact PR-head Release Acceptance is engineering evidence; it is not a GitHub Release, tag, publication, signing, trusted-builder attestation, or release authorization.

Active dependency-update boundary

Draft Dependabot #260 remains open/mechanically mergeable on branch dependabot/uv/uv-build-0.12.5, updating the backend from 0.12.3 to 0.12.5. It has no formal reviews in the fresh inventory and remains ACTIVE-PR evidence only.

Its earlier exact-head CI failure was traced to the same two protected weakref cleanup coverage arcs addressed by dependency-root #233, not to a demonstrated uv_build==0.12.5 incompatibility. Therefore do not classify the dependency update as broken merely from that inherited 99.96% coverage result, and do not copy #233's tests into a competing Dependabot branch. Keep package authority dynamic: immediately before eventual documentation repair and merge, resolve the then-protected package pin again rather than hard-coding either 0.12.3 or branch-only 0.12.5 as future truth.

Required acceptance once the authoritative docs/package surface is writer-safe

Repair the release decision/operator record through normal protected governance:

• update the Proposed ADR's build frontend/backend contract to match the then-current protected package/workflow authority, or create/index a successor if repository ADR policy requires one without pretending ADR 0003 was ever Accepted;
• update docs/doctoring/reproducible-release-evidence.md in the same governed truth change so its Evidence boundary, Operator verification and Build-toolchain failure sections describe the exact then-authoritative frontend/backend contract rather than a predecessor pin;
• preserve an auditable historical note that protected b84f0c9... and exact-source Release Acceptance proved the uv 0.12.3 + uv_build==0.12.3 path;
• explain that PEP 517 build-system requirements resolve independently from ordinary project dependencies and are not made authoritative merely by uv.lock;
• keep ACTIVE dependency updates such as build(deps-dev): bump uv-build from 0.12.3 to 0.12.5 #260 separate from IMPLEMENTED-ON-PROTECTED-MAIN truth until they integrate;
• preserve exact-source release acceptance: exact checked-out source, Python 3.14 support, two clean source trees/builds, deterministic wheel/sdist comparison, and content-bounded evidence identity;
• keep reproducibility separate from signing, trusted-builder provenance, SBOM, attestation, publication, independent approval, and release authorization;
• do not create/publish a version merely to close this docs defect; and
• if source/workflow/test changes become necessary, require exact 100% owned-production statement/branch coverage, 100% public docstrings, supported Python including 3.14, package/lock/build, exact-source Security/SAST, SBOM/provenance/release evidence, zero valid findings/threads, and then-live review/governance on one unchanged final head.

Issue #305 separately owns the protected CHANGELOG statement that incorrectly refers to a setuptools backend floor. Keep the defects distinct unless one writer-safe governed change truthfully resolves both without broadening ownership.

Current writer boundary — refreshed 2026-08-30

Do not patch ADR 0003, the reproducibility doctoring note, pyproject.toml, release workflows, or canonical docs from a new competing branch now.

Current #316 classification removes several false historical writer blockers from the older body:

• old release evidence refs agent/release-evidence-dirfd-hardening, agent/release-evidence-dirfd-hardening-reconcile, agent/release-artifact-dirfd-verification, and agent/release-artifact-dirfd-verification-reconcile are SUPERSEDED_RETAINED; merged feat(release): rebuild reproducible evidence on current main #145 is protected authority for that release-evidence slice;
• docs/canonical-documentation-authority@229f8d3... is an exact ancestor of active Draft docs(recovery): name the live canonical overlay without Draft instructions #229, and the four docs/canonical-documentation-current-main* refs are historical protected-main anchors; those specifically named refs are not independent present-tense documentation writers.

The intended package/release surfaces are nevertheless occupied by actual current writers:

• Draft build(deps-dev): bump uv-build from 0.12.3 to 0.12.5 #260 is the active uv_build dependency writer on pyproject.toml;
• no-PR automation/ruff-0.16.1-lock@fc742fd24f228764116b4bc03c8d967c5f482526 is ACTIVE_WRITER evidence for pyproject.toml/uv.lock;
• no-PR agent/consolidate-maintenance-updates@feda434aa2b086d53cb642ebc3ea8b6cb6bddd74 is ACTIVE_WRITER evidence for package/lock/CI/changelog/container-build surfaces; and
• Draft test(release): define protected-main acceptance entrypoint #247 remains the active protected-main Release Acceptance workflow/test writer downstream of test(recovery): cover stale evidence registry cleanup #233.

Draft #229 is the active canonical-documentation overlay and retains three formal CHANGES_REQUESTED reviews, but its current changed-file set is limited to PRD/TRD, DATA_GOVERNANCE, THREAT_MODEL, DOCUMENTATION_FITNESS, TRACEABILITY, ADR index, UML/ERD and their status-contract tests; it does not currently change ADR 0003 or docs/doctoring/reproducible-release-evidence.md. That non-overlap is not a declaration that either release-doc path is free: the complete non-default branch inventory still contains 123 non-default refs, so exact changed-path comparison of every potentially documentation/release-affecting no-PR/open-PR head is required immediately before any docs mutation.

Thus removing historical false leases and identifying #229 non-overlap do not establish a writer-safe release-doc lane. Before any future source/documentation mutation, freshly refetch protected main, exact ADR 0003/doctoring/package/workflow blobs, every open PR/issue, complete non-default branch inventory and intended-path changed sets, relevant reviews/threads, release evidence, and every live governance surface. Start only from an explicit non-default branch at the then-exact protected-main commit after the exact intended surface is genuinely writer-safe.

Completion boundary

Close only after both protected release documents and the exact package/workflow authority agree through normal review, and a fresh exact-source reproducibility run proves the documented build frontend/backend contract on the final integrated head. Documentation agreement alone is insufficient if the actual build path differs; green builds do not cure stale acquisition/release documentation.

Refs #145, #198, #200, #229, #233, #244, #247, #260, #305, #313, #316.

[seonghobae]

Fresh release-authority cross-check: protected main@b84f0c94154043a3473939c01bb6471de5a129ae still has docs/adr/0003-reproducible-release-evidence.md@6740fbe8d3fb86ab4c2edfe88e5b4e80a4561e78 describing uv_build==0.12.1, while protected pyproject.toml@701c84e7cbff2e9942986c0d3f6e4b746cd48ddc requires uv_build==0.12.3.

There is also an ACTIVE-DRAFT, not protected authority: Dependabot #260 remains exact 19f23e1713ea33d4751712678d1651a22367d8e1, base main@b84f0c94154043a3473939c01bb6471de5a129ae, and changes only pyproject.toml to propose uv-build 0.12.5. Its exact-head CI is non-passing for the inherited protected-main weakref branch-coverage arcs already owned by #233; the Python 3.10/3.12/3.14 unit jobs and Release Acceptance pass, but 100% coverage does not. Therefore #260 must not be treated as current build-backend authority merely because it is newer.

When this documentation surface becomes writer-safe, bind ADR 0003 to the then-integrated protected package/workflow authority, not to either the present 0.12.3 pin or Draft #260 by assumption. If #260 integrates first after its inherited gate is cleared, the documentation repair should evaluate 0.12.5; if it does not, the protected 0.12.3 contract remains the implementation authority to reconcile against.

[seonghobae]

Fresh operational release-evidence cross-check (2026-08-24): Release Acceptance run 32098143650 / job 95593334211 on unchanged #233 explicitly checked out contributor head 5951b7a4d779903b8924abaef2a387cae50b7f54, verified git rev-parse HEAD, used CPython 3.14.7, installed uv 0.12.3, ran uv sync --locked, materialized two clean source trees with git archive, and successfully ran uv build --no-sources twice. The bounded manifest was emitted with SOURCE_COMMIT=5951b7a4d779903b8924abaef2a387cae50b7f54 and uploaded as release-evidence-5951b7a4d779903b8924abaef2a387cae50b7f54.

That exact source tree's pyproject.toml requires uv_build==0.12.3, so the successful reproducibility path consumed package metadata that declares the 0.12.3 backend contract. The runner log does not independently print the resolved uv_build backend version, so do not overstate this as a standalone runtime-version attestation. It does, however, strengthen the protected package/workflow evidence against ADR 0003's stale uv_build==0.12.1 prose.

The documentation/release surface remains occupied by Draft #229, retained docs/canonical-documentation-* refs, release-evidence refs, and active Draft #260 on pyproject.toml; no competing docs/source branch is authorized by this observation. Closure still requires alignment against the then-integrated protected package/workflow authority plus fresh exact-source reproducibility evidence.

[seonghobae]

2026-08-26 toolchain-namespace clarification

Fresh protected-tree verification keeps this defect narrowly scoped to the PEP 517 build backend: docs/adr/0003-reproducible-release-evidence.md says frontend uv 0.12.3 + backend uv_build==0.12.1, while protected pyproject.toml requires uv_build==0.12.3.

Do not conflate that ADR/backend mismatch with read-only central .github#1234. #1234 concerns repositories that declare an exact [tool.uv] required-version for the uv CLI and collide with a trusted central runner version. Protected pg-llm-batch/pyproject.toml currently has no [tool.uv] required-version; its uv_build==0.12.3 build-system requirement is a different version boundary. Likewise, historical #233 OpenCode run 32100082025 failed during trusted-uv executable verification before PR tests, and current protected central materializer now uses the corrected target-triple uv --version assertion; that old failure is not evidence that the pg backend pin is invalid.

Future ADR repair should therefore preserve three distinct identities instead of collapsing them into one “uv version”: (1) release-workflow/frontend uv, (2) PEP 517 backend uv_build, and (3) any future repository-owned [tool.uv] required-version. Each claim must come from the then-current protected workflow/package authority. This clarification changes no source/docs branch and does not make the current documentation surface writer-safe.

[seonghobae]

Fresh writer-boundary correction against unchanged protected main@b84f0c94154043a3473939c01bb6471de5a129ae:

Two no-PR blockers named in the body are now superseded by later #316 evidence. automation/ruff-0.16.1-lock@fc742fd24f228764116b4bc03c8d967c5f482526 and agent/consolidate-maintenance-updates@feda434aa2b086d53cb642ebc3ea8b6cb6bddd74 are SUPERSEDED_RETAINED for their bounded Ruff/lock/consolidated-maintenance intent because normally merged #46 (c2b2f7c4b32e26fdbb549a8481da08d41ad3343e) integrated that maintenance family and remains protected-main ancestry. Preserve those refs for provenance; do not treat them as current package/CI/container writer leases, and do not delete or rewrite them on this finding.

#313 nevertheless remains correctly blocked. Fresh #260 metadata still shows open Draft dependabot/uv/uv-build-0.12.5, mechanically mergeable, and it remains the current pyproject.toml backend-version writer. Draft #247 remains the dedicated Release Acceptance workflow/test writer. Draft #229 remains the canonical-documentation writer but still does not itself establish ownership of ADR 0003 or docs/doctoring/reproducible-release-evidence.md. The full current non-default branch set has not been path-adjudicated for those two exact release-document paths in this invocation, so this correction removes false historical leases only; it does not declare a new documentation lane writer-safe.

Before any eventual repair, refetch the then-protected backend pin and complete exact-path PR/no-PR writer inventory. ACTIVE-PR uv_build==0.12.5 must remain separate from protected-main truth until it actually integrates.