fix(ci): isolate relative includes from flat lock publication

[seonghobae]

Buyer and ecosystem impact

Central coverage-evidence publishes each selected base Python lock under a generated flat name such as requirements-000.txt. A valid source lock containing -r requirements-other.txt loses its source-directory relationship after that rename, so a downstream music or analytics repository can fail before its own tests, branch coverage, or docstring evidence executes.

Root cause

The materializer used one syntax predicate for two different authority boundaries:

• _is_hash_pinned correctly recognizes bounded relative includes as source requirements syntax;
• base_hash_locks incorrectly treated that syntax recognition as permission to publish the referrer independently under a generated flat name.

The same selection path used candidate file names rather than the existing path-aware predicate, omitting independently complete direct locks such as requirements/ci.txt.

Test-first correction

• RED 37d1125b62efa2ec7802ef2ce5707d47896011e4 reproduced both relative include spellings and path-aware nested-lock omission.
• Current exact GREEN head d82718d1011bbcf8acc842159d91972daef4f7d1:
  • keeps _is_hash_pinned and bounded-include syntax diagnostics unchanged;
  • adds documented _is_flat_materializable_lock, which admits only a non-empty standalone closure of exact == package pins with complete SHA-256 hashes;
  • changes base_hash_locks to _is_candidate_lock_path(candidate) plus the flat-publication predicate;
  • retains existing uv.lock export and fixed GitHub Releases download/redirect behavior;
  • binds empty, directive-only, standalone-pin, include-only, both include spellings, referenced-lock retention, and direct requirements-directory discovery to the permanent focused quality workflow;
  • updates the stale CHANGELOG statement; and
  • adds APA 7 doctoring for the immutable publication boundary, operator action, and rollback prohibition.

Current exact-head evidence

Changed files are limited to the materializer, its permanent quality workflow, the focused regression, CHANGELOG, and doctoring. No temporary workflow, dependency, credential, URL, proxy, redirect, package-index, or unrelated control-plane change remains.

Trusted uv Materializer Quality CI run 32144010680 and repository-wide security/review jobs are currently queued on exact head d82718d1011bbcf8acc842159d91972daef4f7d1; queued work is not treated as success.

Merge boundary

Keep Draft until the exact-current-head trusted-uv workflow proves Python 3.10 compatibility, Python 3.14 focused and complete tests, 100% production statement/branch coverage, complete production docstrings, and compilation. Then require all repository checks terminal-success, zero valid unresolved findings, qualifying independent non-author approval, and ordinary protected-branch acceptance. Do not bypass, synthesize, or transfer predecessor evidence.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: cd50f073-940d-4325-90a9-ef03ec8dfdc5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[seonghobae]

@opencode-agent Implement the already-proven minimal GREEN on the existing PR branch only. Exact current head is 83dfdfd4f922aecafcd11415dce2aa59d3b46b51; refetch it before editing and abort if it moves.

Root cause: base_hash_locks uses _is_hash_pinned as flat-publication authority even though relative -r/--requirement directives lose their source-directory meaning after generated renaming. It also uses name-only discovery rather than the existing _is_candidate_lock_path.

Allowed production change:

1. In scripts/ci/materialize_base_python_requirements.py, add a documented _is_flat_materializable_lock(content) that accepts a non-empty requirements closure only when every logical package line is an exact == pin with complete SHA-256 hashes. Keep _is_hash_pinned and bounded-include syntax diagnostics unchanged.
2. In base_hash_locks, select candidate requirements files with _is_candidate_lock_path(candidate) and publish only _is_flat_materializable_lock(content). Preserve current uv.lock behavior and current GitHub Releases downloader/redirect boundary byte-for-byte.
3. Rename the existing RED file to tests/test_uv_flat_lock_publication_boundary.py so the permanent tests/test_uv*.py quality path tracks it, or explicitly add it to the focused trusted-uv workflow. Do not weaken the RED expectations.
4. Add docs/doctoring/trusted-uv-flat-include-isolation.md with root cause, immutable flat-publication boundary, operator action, rollback prohibition, and APA 7 references to pip requirements-file and secure-install documentation.
5. Update the stale Unreleased CHANGELOG bullet so it no longer claims relative includes are safe to materialize under flat generated names.

Required verification on the final exact head:

• focused trusted-uv suite with 100% production statement and branch coverage;
• complete central tests;
• interrogate --fail-under 100 for the materializer;
• Python 3.10 compile compatibility and current stable compile;
• git diff --check;
• no temporary workflow, dependency, credential, URL, proxy, redirect, package-index, or unrelated control-plane change.

Commit only the bounded GREEN and update the PR body with the exact verification evidence. Do not approve, merge, rerun unrelated workflows, or modify BandScope or any sibling repository.