fix(coverage-evidence): retry trusted-uv download on transient network errors

AGENTS.md

@@ -2,3 +2,5 @@
 
 <!-- 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.
+
+Trusted-uv download retries 5xx/429 only; other 4xx fail closed on the first attempt. Materialize accepts only exact SHA-256 pins or a bounded relative `-r` include (no `.`/`..`); a lone `--require-hashes` directive is not trust evidence. See [`ARCHITECTURE.md`](ARCHITECTURE.md) and [`docs/doctoring/trusted-uv-transient-download-retry.md`](docs/doctoring/trusted-uv-transient-download-retry.md).

ARCHITECTURE.md

@@ -0,0 +1,85 @@
+# Architecture — ContextualWisdomLab `.github`
+
+This repository is the organization control plane. It is not naruon and it
+does not own product data. Sibling products remain standalone modules; this
+repo publishes org profile assets, reusable required workflows, and the
+review/merge schedulers those products consume.
+
+## System context
+
+```mermaid
+flowchart LR
+  Buyer["Commercial buyer / reviewer"]
+  Agents["Agents on AGENTS.md"]
+  Project["GitHub Project #1"]
+  Hub["This repo: org .github"]
+  Products["Owned products<br/>naruon · orchestrator · engines"]
+  Runner["Required workflows in each repo context"]
+
+  Buyer --> Hub
+  Agents --> Project
+  Agents --> Hub
+  Project --> Hub
+  Hub --> Runner
+  Runner --> Products
+  Products -->|"standalone or as module"| Buyer
+```
+
+## Trusted-uv download retry gate
+
+```mermaid
+flowchart TD
+  Fetch["Fetch pinned releases.astral.sh archive"]
+  Kind{"Exception class?"}
+  Retry{"Attempts remaining?"}
+  Success["Checksum and member verify"]
+  FailClosed["Fail closed: trust-boundary or exhausted"]
+
+  Fetch --> Kind
+  Kind -->|"OSError including HTTPError"| Retry
+  Kind -->|"RuntimeError redirect or size"| FailClosed
+  Retry -->|"yes"| Fetch
+  Retry -->|"no"| FailClosed
+  Fetch -->|"bytes"| Success
+```
+
+CWE-755: a lone origin 503 is an `OSError` and must retry. A redirect or
+oversized payload is a `RuntimeError` and must not.
+
+## Control-plane data flow
+
+```mermaid
+sequenceDiagram
+  participant PR as Pull request
+  participant RW as Required workflows
+  participant OC as OpenCode reviewer
+  participant SV as sandboxed_verify / web E2E
+  participant MS as Merge scheduler
+
+  PR->>RW: pull_request_target on trusted base
+  RW->>OC: bounded evidence + NVIDIA NIM / OpenCode
+  OC->>SV: PoC command in isolated copy
+  SV-->>OC: redacted stdout/stderr + command metadata
+  OC-->>PR: APPROVE or request changes
+  MS->>PR: merge only on current-head approval + green checks
+```
+
+## Trust boundaries
+
+- Required review workflows execute **base-branch** scripts.
+- Reviewer agents stay `edit: deny`.
+- Logs redact credential shapes. They do not mask operational PII.
+- LLM and scheduled agents bind `NVIDIA_NIM_API_KEY`. They never use
+  `COPILOT_GITHUB_TOKEN`.
+- Rust remains the psychometric arithmetic owner.
+
+## Quality gates
+
+`scripts/ci/` ships with 100% statement/branch coverage and 100%
+docstrings.
+
+## Related durable documents
+
+- [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md)
+- [`docs/doctoring/trusted-uv-transient-download-retry.md`](docs/doctoring/trusted-uv-transient-download-retry.md)
+- [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md)

CHANGELOG.md

@@ -13,6 +13,9 @@ Semantic Versioning where the repository publishes a release.
 
 ### Fixed
 
+- Materialized base Python locks only when every package line is an exact SHA-256 pin or a bounded relative `-r`/`--requirement` include. A lone `--require-hashes` directive, a dotted include such as `./lock.txt`, or `-r other-hashes.txt` no longer enters the trusted build context.
+- Trusted-uv download retry now fail-closes on the first HTTP 4xx except 429, so a missing archive or forbidden origin is not probed three times. 503/429 and non-HTTP `OSError` still use the bounded linear backoff.
+- Retried the trusted-uv archive download a bounded number of times on transient network failures instead of failing the whole `coverage-evidence` job on a single `HTTPError`/`URLError` from the shared `releases.astral.sh` origin, which every pull request's review across the organization fetches; every attempt still runs the unchanged redirect-rejection, host/port pin, size bound, and checksum/member verification, so the fix adds resilience without weakening the trust boundary. Exhaustion tests now assert the linear backoff sequence. The contract now raises the production `HTTPError` 503 type so CWE-755 cannot recast that OSError subclass as an unretried trust-boundary failure.
 - Bounded the Strix quality self-test's deterministic timeout fixtures to 3-second process and 5-second fake-sleep budgets so exact-head policy evidence completes inside the existing job limit without changing production Strix scanner timeouts, providers, credentials, or review semantics.
 - Allowed commas and ASCII parentheses in the bounded Strix changed-file path policy so legal tracked Packrat fixtures can receive exact-head security analysis, while rejecting raw `..` components before normalization and keeping controls, backslashes, whitespace ambiguity, and shell punctuation fail-closed.
 - Bound each review-agent invocation key to the wrapper's complete canonical payload, including the base branch and requesting actor; altered fields with a valid-format key now fail before durable-leader election or forwarding, and wrapper write permission is job-scoped.

CLAUDE.md

@@ -63,6 +63,9 @@ Details: `README.md` and `PR_GOVERNANCE_AUDIT.md`.
   dependency sets (see below).
 - `fuzz/` + `.clusterfuzzlite/` — Atheris fuzz targets for the review-output normalizer and the
   ClusterFuzzLite discovery marker.
+- `ARCHITECTURE.md` — control-plane mermaid (system context, trusted-uv
+  retry gate, review sequence, trust boundaries). Reconstruct from the repo,
+  not private agent memory.
 - `docs/` — master context, Project protocol, `org-required-workflow-rollout.md`,
   `scorecard-governance.md`, SBOM inventory.
 - `.jules/` — recorded performance (`bolt.md`) and security (`sentinel.md`) learnings from past work
@@ -126,3 +129,5 @@ repeatable compile command.
   cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not
   private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and
   apply here.
+
+Trusted-uv download retries 5xx/429 only. See `ARCHITECTURE.md`.

docs/doctoring/trusted-uv-transient-download-retry.md

@@ -0,0 +1,36 @@
+# Trusted-uv transient download retry
+
+## Incident and buyer impact
+
+Materialize accepts only exact SHA-256 pins or a bounded relative `-r`
+include; a lone `--require-hashes` line is not lock evidence.
+
+Every organization pull request runs `coverage-evidence`, which downloads one
+pinned `uv` archive from `releases.astral.sh`. A single transient `HTTPError`
+on that shared origin failed the gate and produced a false-negative
+OpenCode `REQUEST_CHANGES` on otherwise healthy heads
+(`ContextualWisdomLab/naruon#1293`, `ContextualWisdomLab/naruon#1300`).
+
+## Decision
+
+Retry only transient `OSError` a bounded three times with linear backoff:
+HTTP 5xx, 429, and non-HTTP network errors. HTTP 4xx other than 429 fail
+on the first attempt (RFC 9110 client-side policy). Trust-boundary
+violations (`RuntimeError` for redirect, host/port, or oversized payload)
+are never retried. Each attempt still pins scheme, host, port, size,
+checksum, and archive member.
+
+This follows the HTTP retry discipline for transient server/network failures
+and does not retry client-side policy failures (Fielding et al., 2022,
+§15.5). CWE-755 forbids mishandling exceptional conditions (MITRE, 2026):
+`HTTPError` is an `OSError` subclass, so a lone 503 must enter the bounded
+retry; `RuntimeError` trust-boundary violations must not.
+
+## References
+
+MITRE. (2026). *CWE-755: Improper handling of exceptional conditions*.
+https://cwe.mitre.org/data/definitions/755.html
+
+Fielding, R., Nottingham, M., & Reschke, J. (Eds.). (2022). *HTTP semantics*
+(RFC 9110). Internet Engineering Task Force.
+https://doi.org/10.17487/RFC9110