fix(coverage): trust validated Python head locks

.github/workflows/opencode-review-dispatch.yml

@@ -649,9 +649,17 @@ jobs:
                   break
                   ;;
               esac
-              # Any text file below a requirements directory may be a bounded
-              # include target of a base lock, so retain materialization
-              # conservatively instead of relying on path depth alone.
+              # Any tracked .txt file may be a bounded include target of a base
+              # lock, so retain materialization conservatively instead of
+              # relying on path depth alone.
+              case "$changed_basename" in
+                *.txt)
+                  python_coverage_required=1
+                  break
+                  ;;
+              esac
+              # Includes with the other supported suffix remain recognized
+              # below requirements directories.
               case "/$changed_path/" in
                 */requirements/*)
                   case "$changed_basename" in
@@ -667,6 +675,7 @@ jobs:
               python3 -I "$GITHUB_WORKSPACE/scripts/ci/materialize_base_python_requirements.py" \
                 --repo-root "$COVERAGE_SOURCE_WORKDIR" \
                 --base-sha "$PR_BASE_SHA" \
+                --head-sha "$PR_HEAD_SHA" \
                 --output-dir "$coverage_build_dir/base-python-requirements"
             else
               mkdir -p "$coverage_build_dir/base-python-requirements"

ARCHITECTURE.md

@@ -151,9 +151,11 @@ tests pin workflow structure and governance prose so drift fails closed. The
 trusted `uv` exporter is downloaded from the literal GitHub Releases URL for
 `uv` 0.12.1; `releases.astral.sh` is not the network sink.
 An exact-base `uv.lock` may additionally expose source from an organization-owned
-GitHub repository pinned to a full commit: the secret-free image build verifies
-the fetched revision and makes its source importable without running package
-build or installation hooks. Pull-request execution remains networkless.
+GitHub repository pinned to a full commit. When a `uv.lock` project changes, the
+same export and source validation may use the exact current-head lock and sibling
+metadata; unchanged projects remain base-bound. The secret-free image build
+verifies the fetched revision and makes its source importable without running
+package build or installation hooks. Pull-request execution remains networkless.
 Root-level lock files are independent environments unless an explicit include
 relationship says otherwise; only one unambiguous two-file supplement pair may
 be recovered together, so unrelated toolchains cannot create a synthetic

CHANGELOG.md

@@ -5,6 +5,20 @@ this file. The format follows Keep a Changelog, and versioned releases follow
 Semantic Versioning where the repository publishes a release.
 
 ## [Unreleased]
+- Let OpenCode coverage replace a changed base Python lock with the validated
+  current-head flat lock, and revalidate bounded includes beneath unchanged
+  parents against the exact HEAD tree; changed includes must remain flat and
+  pinned, while deleted or invalid includes fail closed. This keeps Python
+  dependency updates measurable without weakening `--require-hashes` or
+  `--only-binary=:all:`.
+- Re-export changed or newly added `uv.lock` projects from the exact HEAD with
+  the existing frozen/offline exporter, while removing deleted projects' base
+  registry and VCS inputs and retaining unchanged projects at the base revision;
+  changed or deleted projects are inventoried before any base export so a stale
+  base project cannot block its exact-head repair.
+- Keep exact-head Python coverage materialization enabled for every tracked
+  `.txt` change because a bounded include cannot be identified safely from its
+  path, and reject malformed base or HEAD SHAs before any Git read.
 - Raise `contextual_orchestrator_review_sidecar.sh`'s
   `ORCHESTRATOR_CATALOG_FAMILY_CAP` default from 4 to 8: root-caused the
   live "no provider route passed the Strix plain-chat preflight" outage

docs/doctoring/opencode-exact-vcs-dependency-evidence.md

@@ -3,11 +3,14 @@
 ## Decision
 
 The OpenCode coverage image may expose a Python dependency directly from source
-only when the validated base branch's frozen `uv.lock` names an HTTPS GitHub
-repository owned by `ContextualWisdomLab` and a full 40-character Git commit.
-Registry dependencies remain exact-version, SHA-256-pinned `pip` installs.
-
-The trusted materializer separates those two dependency classes. The networked,
+only when the validated base branch's frozen `uv.lock`, or a changed or newly
+added exact-head `uv.lock` project selected for coverage, names an HTTPS GitHub
+repository owned by `ContextualWisdomLab` and a full 40-character Git commit. Registry
+dependencies remain exact-version, SHA-256-pinned `pip` installs.
+
+The trusted materializer separates those two dependency classes. Unchanged
+projects remain base-bound; changed or newly added projects are exported from
+the exact HEAD with the same isolated frozen/offline exporter. The networked,
 secret-free image build fetches each approved source revision, verifies that
 `FETCH_HEAD` and the checked-out `HEAD` equal the locked commit, removes Git
 metadata, verifies a normalized package import root, and records only that
@@ -31,8 +34,10 @@ product's current-head tests passing.
   organization origin fail closed.
 - Duplicate references to one repository must resolve to one commit; conflicting
   revisions fail before the image build.
-- Only metadata read from the validated base SHA can select a dependency. Pull
-  request source cannot modify the networked image build inputs.
+- Only metadata read from the validated base SHA or a changed or newly added
+  project in the exact validated HEAD can select a dependency. Pull request
+  source cannot
+  modify the networked image build inputs outside those immutable revisions.
 - Source dependencies are import-only. No `pip install`, PEP 517 backend, setup
   hook, or dependency lifecycle script runs while the network is available.
 - The source repository must be publicly fetchable without credentials, expose

docs/doctoring/opencode-python-head-lock-trust.md

@@ -0,0 +1,79 @@
+# OpenCode coverage validated-head Python locks
+
+검토 기준일: **2026-08-29**
+
+## Decision
+
+OpenCode coverage may use a pull request's changed Python requirements lock when
+the lock is read from the authenticated, validated HEAD SHA and every logical
+requirement is an exact `==` pin with one or more complete SHA-256 hashes. A
+changed HEAD lock must be flat: URLs, VCS sources, relative includes, and
+unpinned lines do not cross into the networked coverage-image build context.
+
+An unchanged lock remains materialized from the validated base SHA. When a
+tracked base lock changes, the validated flat HEAD lock replaces it rather than
+installing both revisions. For an unchanged base lock with a bounded relative
+include, the include blob is compared with the exact HEAD tree: a changed
+include is materialized only when it remains flat and fully SHA-256 pinned, while
+deleted or invalid content fails closed. A base lock that becomes unbounded
+fails closed. A changed or newly added `uv.lock` project with a regular sibling
+`pyproject.toml` is re-exported from the exact HEAD through the existing frozen,
+offline, checksum-validating exporter; deleted projects remove their base
+registry and VCS inputs, and unchanged projects remain base-bound. Base and HEAD
+`uv.lock` inventories are completed before export, so a changed or deleted HEAD
+project never requires its stale base export to succeed first.
+
+The workflow keeps this materialization enabled for every tracked `.txt` change:
+the path alone cannot prove that a file is not a bounded include target. Content
+validation still decides whether that candidate can enter the trusted image.
+
+## Root cause
+
+The coverage image was built only from `PR_BASE_SHA` Python locks. A legitimate
+dependency pull request could therefore add a platform wheel hash to its
+current-head lock, while the image builder still saw the older base file. Pip
+then failed before PR tests because the compatible wheel's hash was absent from
+the stale lock. The JavaScript materializer already handled this case by
+validating and recording changed HEAD locks; Python had no equivalent path.
+
+## Security boundary
+
+The central workflow and materializer validate the exact base and head revisions
+before any Git tree read. Only a regular candidate lock from the exact HEAD is
+read, and only a flat SHA-256-pinned file can replace a base lock. Changed
+`uv.lock` projects reuse the same isolated exporter against exact HEAD
+`uv.lock` and sibling metadata, then apply the established registry hash and
+organization-owned full-commit VCS validation. A bounded
+include beneath an unchanged base lock is likewise read from HEAD only after
+its exact base/head blob comparison and regular-file check; its content must be
+flat and fully pinned. The image installer retains
+`pip install --require-hashes --only-binary=:all:`; source distributions, build
+backends, VCS dependencies, unbounded requirements, deleted includes, and
+invalid include content remain rejected or outside this path. The later PR
+sandbox remains networkless and credential-free.
+
+This is a provenance and compatibility repair, not an approval or merge
+mechanism. Current-head OpenCode, Strix, other required Checks, review threads,
+and protected-branch rules remain independent gates.
+
+## Verification contract
+
+Regression coverage proves that a changed exact-head lock replaces stale base
+content; a changed, deleted, or invalid include beneath an unchanged parent is
+handled from the exact HEAD; and changed, deleted, registry-only, VCS-only, and
+mixed `uv.lock` projects replace or remove every base export component before
+image build. Workflow contract coverage proves that the materializer receives
+both `PR_BASE_SHA` and `PR_HEAD_SHA`. The central quality gate must retain
+complete statement, branch, and docstring coverage.
+
+## APA 7th references
+
+Python Packaging Authority. (n.d.). *Secure installs*. pip documentation.
+Retrieved August 29, 2026, from
+https://pip.pypa.io/en/stable/topics/secure-installs/
+
+Python Packaging Authority. (n.d.). *pip install*. pip documentation. Retrieved
+August 29, 2026, from https://pip.pypa.io/en/stable/cli/pip_install/
+
+Supply-chain Levels for Software Artifacts. (2025). *SLSA specification (version
+1.2)*. https://slsa.dev/spec/v1.2/

docs/doctoring/trusted-uv-lock-materialization.md

@@ -4,9 +4,12 @@
 
 Central coverage automation may translate a tracked `uv.lock` from the exact
 validated pull-request base revision into a pip-compatible, hash-pinned
-requirements closure. The translation must not depend on a mutable runner tool,
-repository-head dependency metadata, ambient runner configuration, or network
-access during export.
+requirements closure. When current-head materialization is requested, a changed
+or newly added `uv.lock` project is translated from its exact HEAD lock and
+sibling metadata; deleted projects remove their base export, and unchanged
+projects stay base-bound. The translation must not depend on a mutable runner
+tool, repository-head dependency metadata outside the selected exact revision,
+ambient runner configuration, or network access during export.
 
 The implementation therefore:
 
@@ -16,9 +19,16 @@ The implementation therefore:
    same immutable revision; an absent sibling is an explicit orphan, while a
    read failure for an inventoried blob is fatal and cannot be misclassified as
    absence;
-3. installs one process-wide urllib opener with an empty proxy map and a redirect
+3. inventories the base and current-head `uv.lock` projects plus sibling metadata
+   blob IDs before export; unchanged projects use the base revision, changed or
+   newly added projects use HEAD, and deleted projects remove their base registry
+   and VCS entries;
+4. compares the base and current-head `uv.lock` plus sibling metadata blob IDs
+   before re-exporting a changed project; a changed project uses the same isolated
+   exporter and exact registry/VCS validators against HEAD;
+5. installs one process-wide urllib opener with an empty proxy map and a redirect
    handler that rejects every redirect before urllib creates a target request;
-4. downloads one fixed official `uv` archive from the literal GitHub Releases
+6. downloads one fixed official `uv` archive from the literal GitHub Releases
    HTTPS URL and accepts a response only when its parsed origin remains HTTPS on
    `github.com`, `release-assets.githubusercontent.com`, or
    `objects.githubusercontent.com` with the absent or explicit default port 443;
@@ -28,22 +38,22 @@ The implementation therefore:
    because that vanity host now returns HTTP 403 for the pinned 0.12.1 archive
    (ContextualWisdomLab/.github#1109) while the GitHub Releases asset keeps the
    same SHA-256 digest;
-5. verifies the bounded archive with a pinned SHA-256 digest before extraction;
-6. accepts only the expected regular-file tar member within explicit size bounds;
-7. writes the executable with mode `0755` and verifies that it reports the exact
+7. verifies the bounded archive with a pinned SHA-256 digest before extraction;
+8. accepts only the expected regular-file tar member within explicit size bounds;
+9. writes the executable with mode `0755` and verifies that it reports the exact
    pinned `uv` version;
-8. executes `uv export` with `--frozen`, `--offline`, `--no-cache`,
+10. executes `uv export` with `--frozen`, `--offline`, `--no-cache`,
    `--no-progress`, `--color never`, `--no-emit-project`, and `--no-editable` in
    an isolated temporary project;
-9. supplies a minimal environment with isolated home, temporary, cache, and
+11. supplies a minimal environment with isolated home, temporary, cache, and
    configuration directories, disables dotenv loading and managed Python
    downloads, and does not inherit arbitrary runner variables;
-10. keeps project metadata discovery enabled because the reconstructed
+12. keeps project metadata discovery enabled because the reconstructed
     `pyproject.toml` is an authoritative input; `--no-config` is deliberately not
     used because uv documents that it disables `pyproject.toml` discovery;
-11. rejects every nonempty export unless every logical line is an exact normalized
+13. rejects every nonempty export unless every logical line is an exact normalized
     package `==` pin followed only by complete SHA-256 hashes; and
-12. exposes only generated requirements files and a source manifest to the later
+14. exposes only generated requirements files and a source manifest to the later
     networkless coverage environment.
 
 ## Standards and current-tool rationale
@@ -92,8 +102,9 @@ executable payload identity.
 Nested standalone services are supported: a repository may contain several
 independent directories, each with its own sibling `pyproject.toml` and
 `uv.lock`; each pair is read and exported independently from the immutable base
-revision. This fits the organization’s standalone-product plus reusable-module
-MSA contract without copying central review logic into product repositories.
+revision, or from the exact HEAD when its lock or metadata changed. This fits
+the organization’s standalone-product plus reusable-module MSA contract without
+copying central review logic into product repositories.
 
 A true uv workspace can require member `pyproject.toml` files in addition to the
 root lock and root project metadata. The current materializer does not
@@ -123,6 +134,8 @@ Regression coverage must prove:
 - continued project metadata discovery with no `--no-config` regression;
 - timeout, process, parse, and exporter failures fail closed;
 - orphan locks and empty third-party closures remain nonfatal and explicit;
+- changed, deleted, registry-only, VCS-only, and mixed current-head `uv.lock`
+  projects replace or remove their base registry and VCS manifests;
 - every nonempty line is a normalized exact package pin with one or more complete
   SHA-256 hashes; and
 - `pyproject.toml` enables branch measurement and the changed production module