fix(coverage): admit exact base VCS sources

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

@@ -726,8 +726,82 @@ jobs:
               --only-binary=:all: \
               -r /tmp/requirements-opencode-review-ci-hashes.txt \
             && rm -f /tmp/requirements-opencode-review-ci-hashes.txt
-          COPY install-base-python-locks.py /usr/local/libexec/install-base-python-locks.py
           COPY base-python-requirements /tmp/base-python-requirements
+          RUN set -eu; \
+              mkdir -p /opt/base-vcs-dependencies; \
+              site_packages="$(python3 -c 'import site; print(site.getsitepackages()[0])')"; \
+              path_file="${site_packages}/opencode-base-vcs-dependencies.pth"; \
+              : >"$path_file"; \
+              dependency_index=0; \
+              dependency_list=/tmp/base-vcs-dependencies.tsv; \
+              jq -r '.[] | [.import_name, .repository, .commit] | @tsv' \
+                /tmp/base-python-requirements/vcs-manifest.json >"$dependency_list"; \
+              while IFS="$(printf '\t')" read -r import_name repository commit; do \
+                    destination="$(printf '/opt/base-vcs-dependencies/dependency-%03d' "$dependency_index")"; \
+                    git init --quiet "$destination"; \
+                    git -C "$destination" remote add origin \
+                      "https://github.com/ContextualWisdomLab/${repository}.git"; \
+                    git -C "$destination" -c protocol.version=2 fetch \
+                      --quiet --no-tags --depth=1 origin "$commit"; \
+                    test "$(git -C "$destination" rev-parse FETCH_HEAD)" = "$commit"; \
+                    git -C "$destination" checkout --quiet --detach FETCH_HEAD; \
+                    test "$(git -C "$destination" rev-parse HEAD)" = "$commit"; \
+                    rm -rf -- "$destination/.git"; \
+                    import_root=''; \
+                    python_root=''; \
+                    candidate_count=0; \
+                    for candidate in \
+                      "$destination/src/$import_name" \
+                      "$destination/src/$import_name.py" \
+                      "$destination/$import_name" \
+                      "$destination/$import_name.py"; do \
+                      if [ -e "$candidate" ] || [ -L "$candidate" ]; then \
+                        import_root="$candidate"; \
+                        candidate_count=$((candidate_count + 1)); \
+                      fi; \
+                    done; \
+                    if [ "$candidate_count" -ne 1 ]; then \
+                      printf 'locked VCS source %s has a missing or ambiguous import root for %s\n' \
+                        "$repository" "$import_name" >&2; \
+                      exit 1; \
+                    fi; \
+                    if [ -L "$import_root" ] \
+                      || { [ -d "$import_root" ] \
+                        && { [ ! -f "$import_root/__init__.py" ] \
+                          || [ -L "$import_root/__init__.py" ]; }; }; then \
+                      printf 'locked VCS source %s has a namespace or linked import root for %s\n' \
+                        "$repository" "$import_name" >&2; \
+                      exit 1; \
+                    fi; \
+                    if find "$destination" -type l -print -quit | grep -q .; then \
+                      printf 'locked VCS source %s contains a symbolic-link layout\n' \
+                        "$repository" >&2; \
+                      exit 1; \
+                    fi; \
+                    if find "$destination" -type f \
+                      \( -name '*.so' -o -name '*.pyd' -o -name '*.dll' -o -name '*.dylib' \) \
+                      -print -quit | grep -q .; then \
+                      printf 'locked VCS source %s contains a compiled extension\n' \
+                        "$repository" >&2; \
+                      exit 1; \
+                    fi; \
+                    if find "$destination" -type d \
+                      \( -name '*.dist-info' -o -name '*.egg-info' \) \
+                      -print -quit | grep -q .; then \
+                      printf 'locked VCS source %s contains installed distribution metadata\n' \
+                        "$repository" >&2; \
+                      exit 1; \
+                    fi; \
+                    case "$import_root" in \
+                      "$destination/src/"*) python_root="$destination/src" ;; \
+                      *) python_root="$destination" ;; \
+                    esac; \
+                    printf '%s\n' "$python_root" >>"$path_file"; \
+                    dependency_index=$((dependency_index + 1)); \
+                  done <"$dependency_list"; \
+              rm -f -- "$dependency_list"; \
+              chmod -R a+rX /opt/base-vcs-dependencies "$path_file"
+          COPY install-base-python-locks.py /usr/local/libexec/install-base-python-locks.py
           RUN python3 -I /usr/local/libexec/install-base-python-locks.py \
                 --requirements-root /tmp/base-python-requirements \
             && rm -rf /tmp/base-python-requirements \

AGENTS.md

@@ -3,7 +3,11 @@
 <!-- CWL-ENTRY -->
 > **Agents: read the master context FIRST.** Before any work, read [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) (mission · naruon-as-platform + inter-component UML · cross-cutting disciplines · conventions · roadmap · current state), the live **GitHub Project #1** <https://github.com/orgs/ContextualWisdomLab/projects/1> (work/roadmap source of truth), the full spec **ContextualWisdomLab/naruon#974**, and operate the Project per [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md). The repo/Project — not any private agent memory — is the source of truth.
 
-Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include (no `.`/`..`); a lone `--require-hashes` directive is not trust evidence. See [`docs/doctoring/hourly-nvidia-nim-autofix.md`](docs/doctoring/hourly-nvidia-nim-autofix.md).
+Materialize accepts only exact SHA-256 pins, a bounded relative `-r` include
+(no `.`/`..`), or an organization-owned HTTPS Git source pinned to a full
+commit and exposed without running build hooks; a lone `--require-hashes`
+directive is not trust evidence. See
+[`docs/doctoring/opencode-exact-vcs-dependency-evidence.md`](docs/doctoring/opencode-exact-vcs-dependency-evidence.md).
 Conflict-scope roots fail closed when the immediate parent directory is a symbolic link.
 OriginWeave hourly NVIDIA NIM repair is a thin caller at minute 10. See [`docs/doctoring/originweave-hourly-review-caller.md`](docs/doctoring/originweave-hourly-review-caller.md).
 nonnest2 hourly NVIDIA NIM repair is a thin caller at minute 16. See [`docs/doctoring/nonnest2-hourly-review-caller.md`](docs/doctoring/nonnest2-hourly-review-caller.md).

ARCHITECTURE.md

@@ -135,6 +135,10 @@ CI installs Python tools only with `pip install --require-hashes`. Contract
 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.
 
 ## Related durable documents
 
@@ -150,6 +154,8 @@ trusted `uv` exporter is downloaded from the literal GitHub Releases URL for
   — current increment's repair-worker decision and APA 7th citations.
 - [`docs/doctoring/opencode-llm-review-publication.md`](docs/doctoring/opencode-llm-review-publication.md)
   — LLM probe publication without inventing observed proof.
+- [`docs/doctoring/opencode-exact-vcs-dependency-evidence.md`](docs/doctoring/opencode-exact-vcs-dependency-evidence.md)
+  — import-only exact source dependencies for networkless coverage.
 - [`docs/doctoring/fast-mlsirm-hourly-review-caller.md`](docs/doctoring/fast-mlsirm-hourly-review-caller.md)
   — product-specific psychometric repair heartbeat and scientific gates.
 - [`docs/doctoring/exact-artifact-sbom-attestation.md`](docs/doctoring/exact-artifact-sbom-attestation.md)

CHANGELOG.md

@@ -6,6 +6,11 @@ Semantic Versioning where the repository publishes a release.
 
 ## [Unreleased]
 
+- Fix OpenCode coverage evidence for exact-base, organization-owned Python VCS
+  dependencies without weakening registry hashes or the networkless PR sandbox,
+  reject namespace, ambiguous, linked, native-extension, and installed-metadata
+  layouts, and make exact roots readable by the unprivileged coverage user.
+
 ### Added
 
 - Added an hourly organization commercial-readiness coordinator that discovers writable repositories, honors enabled dedicated writer leases and fully paginated live writer runs, refetches exact repository/workflow/run/PR state before dispatch, rotates bounded review-repair and opt-in NVIDIA OpenCode product-development targets, fails nonzero on fleet-wide inspection or dispatch outages, retains three-day JSON receipts, and keeps the existing 15-minute merge scheduler authoritative.

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

@@ -0,0 +1,79 @@
+# OpenCode exact VCS dependency evidence
+
+## 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,
+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
+repository root or its `src` directory in a Python path file. It does not run
+dependency build or installation code. The pull-request tree still runs later
+with no network and no credentials.
+
+## Root cause
+
+LineageWeave's protected base lock contains RankWeave at its immutable release
+commit because the current RankWeave release is not yet available from PyPI.
+`uv export` therefore emitted one exact VCS requirement alongside fully hashed
+registry requirements. The former materializer rejected the complete export,
+so OpenCode never reached tests and repeatedly requested changes despite the
+product's current-head tests passing.
+
+## Safety boundary
+
+- Symbolic refs, abbreviated commits, non-HTTPS schemes, credentials, ports,
+  query strings, fragments, subdirectories, and repositories outside the exact
+  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.
+- 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
+  the normalized top-level import package directly or under `src`, and remain a
+  pure-Python leaf dependency. Private repositories, environment-marked VCS
+  requirements, namespace/layout aliases, installed-distribution metadata,
+  entry points, compiled extensions, and registry packages that require the VCS
+  distribution fail closed instead of expanding the secret-free build boundary.
+- The checkout roots and path file are explicitly world-readable so the later
+  networkless coverage container can run as UID 65532 independently of the
+  image builder's umask.
+- This records exact source inputs for a test image; it does not claim a SLSA
+  build level or substitute for upstream package publication and attestation.
+
+These controls follow pip's recommendation to use full VCS commit hashes and
+SLSA 1.2's treatment of Git revisions as immutable identifiers, while retaining
+the isolated, ephemeral test execution boundary (Python Packaging Authority,
+2026; Supply-chain Levels for Software Artifacts, 2025). They also support the
+SSDF practice of preserving dependency provenance and preventing recurrence of
+toolchain failures (Souppaya et al., 2022).
+
+## Verification
+
+Regression tests cover the real LineageWeave export shape, rejection of unsafe
+VCS forms, conflicting commits, deterministic manifests, exact-fetch workflow
+commands, and the existing registry hash contract. Before source-only Python
+path publication, the image build requires exactly one normalized root, a
+regular `__init__.py` for packages, and no symbolic links, compiled extensions,
+or installed distribution metadata. Namespace, alias/ambiguous, and native
+layouts therefore fail the build. The central Python quality workflow retains
+100% statement/branch and docstring coverage.
+
+## References
+
+Python Packaging Authority. (2026). *VCS support*. pip documentation v26.2.
+https://pip.pypa.io/en/stable/topics/vcs-support/
+
+Souppaya, M., Scarfone, K., & Dodson, D. (2022). *Secure software development
+framework (SSDF) version 1.1: Recommendations for mitigating the risk of
+software vulnerabilities* (NIST Special Publication 800-218). National
+Institute of Standards and Technology. https://doi.org/10.6028/NIST.SP.800-218
+
+Supply-chain Levels for Software Artifacts. (2025). *SLSA specification
+(Version 1.2)*. https://slsa.dev/spec/v1.2/