fix(coverage): validate nested npm metadata through canonical pins

.github/workflows/npm-nested-metadata-validation-quality-ci.yml

@@ -0,0 +1,136 @@
+name: npm Nested Metadata Validation Quality CI
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - ".github/workflows/npm-nested-metadata-validation-quality-ci.yml"
+      - "scripts/ci/materialize_base_javascript_packages.py"
+      - "tests/conftest.py"
+      - "tests/test_javascript_materializer_creation_cleanup_security.py"
+      - "tests/test_javascript_materializer_descriptor_ancestry.py"
+      - "tests/test_javascript_materializer_existing_directory_coverage.py"
+      - "tests/test_javascript_materializer_output_edge_coverage.py"
+      - "tests/test_javascript_materializer_output_security.py"
+      - "tests/test_materialize_base_javascript_packages.py"
+      - "tests/test_npm_nested_metadata_lock_validation.py"
+      - "docs/doctoring/npm-nested-metadata-canonical-pins.md"
+      - "requirements-opencode-review-ci-hashes.txt"
+      - "CHANGELOG.md"
+  push:
+    branches: [main]
+    paths:
+      - ".github/workflows/npm-nested-metadata-validation-quality-ci.yml"
+      - "scripts/ci/materialize_base_javascript_packages.py"
+      - "tests/conftest.py"
+      - "tests/test_javascript_materializer_creation_cleanup_security.py"
+      - "tests/test_javascript_materializer_descriptor_ancestry.py"
+      - "tests/test_javascript_materializer_existing_directory_coverage.py"
+      - "tests/test_javascript_materializer_output_edge_coverage.py"
+      - "tests/test_javascript_materializer_output_security.py"
+      - "tests/test_materialize_base_javascript_packages.py"
+      - "tests/test_npm_nested_metadata_lock_validation.py"
+      - "docs/doctoring/npm-nested-metadata-canonical-pins.md"
+      - "requirements-opencode-review-ci-hashes.txt"
+      - "CHANGELOG.md"
+
+concurrency:
+  group: npm-nested-metadata-quality-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  python-310-compatibility:
+    name: Python 3.10 compatibility
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+      - name: Checkout exact source revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Set up Python 3.10
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.10"
+      - name: Compile implementation and contracts
+        run: |
+          python -m compileall -q \
+            scripts/ci/materialize_base_javascript_packages.py \
+            tests/conftest.py \
+            tests/test_javascript_materializer_descriptor_ancestry.py \
+            tests/test_javascript_materializer_existing_directory_coverage.py \
+            tests/test_javascript_materializer_output_edge_coverage.py \
+            tests/test_javascript_materializer_output_security.py \
+            tests/test_materialize_base_javascript_packages.py \
+            tests/test_npm_nested_metadata_lock_validation.py
+
+  python-314-quality:
+    name: Python 3.14 complete quality
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - name: Harden runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+      - name: Checkout exact source revision
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          persist-credentials: false
+      - name: Set up Python 3.14
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: requirements-opencode-review-ci-hashes.txt
+      - name: Install exact hash-locked quality tooling
+        run: >-
+          python -m pip install --disable-pip-version-check --require-hashes
+          -r requirements-opencode-review-ci-hashes.txt
+      - name: Run focused tests with complete production branch coverage
+        run: |
+          python -m coverage erase
+          python -m coverage run --branch -m pytest -q \
+            tests/test_javascript_materializer_creation_cleanup_security.py \
+            tests/test_javascript_materializer_descriptor_ancestry.py \
+            tests/test_javascript_materializer_existing_directory_coverage.py \
+            tests/test_javascript_materializer_output_edge_coverage.py \
+            tests/test_javascript_materializer_output_security.py \
+            tests/test_materialize_base_javascript_packages.py \
+            tests/test_npm_nested_metadata_lock_validation.py
+          python -m coverage report \
+            --include=scripts/ci/materialize_base_javascript_packages.py \
+            --show-missing \
+            --fail-under=100
+      - name: Enforce complete production docstrings and compilation
+        run: |
+          python -m interrogate --fail-under 100 scripts/ci/materialize_base_javascript_packages.py
+          python -m compileall -q \
+            scripts/ci/materialize_base_javascript_packages.py \
+            tests/conftest.py \
+            tests/test_javascript_materializer_creation_cleanup_security.py \
+            tests/test_javascript_materializer_descriptor_ancestry.py \
+            tests/test_javascript_materializer_existing_directory_coverage.py \
+            tests/test_javascript_materializer_output_edge_coverage.py \
+            tests/test_javascript_materializer_output_security.py \
+            tests/test_materialize_base_javascript_packages.py \
+            tests/test_npm_nested_metadata_lock_validation.py
+      - name: Run complete central regression suite
+        run: |
+          python -m coverage erase
+          python -m coverage run -m pytest tests -q
+          python -m coverage report --show-missing --fail-under=100
+      - name: Verify clean patches
+        run: git diff --check

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.
+
+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/npm-nested-metadata-canonical-pins.md`](docs/doctoring/npm-nested-metadata-canonical-pins.md).

ARCHITECTURE.md

@@ -0,0 +1,99 @@
+# 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
+```
+
+## Nested npm metadata pins
+
+```mermaid
+flowchart TD
+  Entry["packages map entry"]
+  Link{"workspace link?"}
+  Fields{"resolved and integrity?"}
+  Root{"canonical root?"}
+  Accept["Accept after HTTPS SHA-512 pin"]
+  Reject["Fail closed"]
+
+  Entry --> Link
+  Link -->|"yes"| Accept
+  Link -->|"no"| Fields
+  Fields -->|"both"| Accept
+  Fields -->|"one"| Reject
+  Fields -->|"neither"| Root
+  Root -->|"yes"| Reject
+  Root -->|"no"| Accept
+```
+
+An explicit port, userinfo, query, or fragment is not the default npm
+registry origin. Publication uses no-follow, descriptor-relative opens.
+
+## 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. A PR that edits
+  those workflows cannot widen its own `pull_request_target` token.
+- Reviewer agents stay `edit: deny`. They judge; they do not implement.
+- Sandbox helpers copy the workspace, drop secret environment values unless
+  explicitly allowlisted by **name**, and run subprocesses with `shell=False`.
+- Logs and review receipts redact credential shapes (tokens, bearer values,
+  known provider prefixes). They do not mask operational PII that the
+  control plane must process.
+- LLM and scheduled agents bind `NVIDIA_NIM_API_KEY` (env may be
+  `NVIDIA_API_KEY`). They never use `COPILOT_GITHUB_TOKEN`. Existing
+  review-agent key schemes stay unchanged.
+
+## Quality gates
+
+`scripts/ci/` ships with 100% statement/branch coverage and 100% docstrings.
+CI installs Python tools only with `pip install --require-hashes`. Contract
+tests pin workflow structure and governance prose so drift fails closed.
+
+## Related durable documents
+
+- [`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) — mission and
+  ecosystem.
+- [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md)
+  — Project #1 operation.
+- [`PR_GOVERNANCE_AUDIT.md`](PR_GOVERNANCE_AUDIT.md) — live review/merge
+  contract.
+- [`docs/doctoring/npm-nested-metadata-canonical-pins.md`](docs/doctoring/npm-nested-metadata-canonical-pins.md)
+  — current increment's lockfile decision and APA 7th citations.

CHANGELOG.md

@@ -13,6 +13,10 @@ 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.
+- Accepted npm v2/v3 metadata-only nested workspace and peer locations only when one exact scoped or unscoped canonical root package carries the same version, HTTPS npm-registry tarball, and canonical SHA-512 integrity, while continuing to reject malformed identities, partial pins, metadata-only roots, alternate origins, and version drift. The decision record now cites RFC 3986 so an explicit port, userinfo, query, or fragment cannot masquerade as the default npm registry origin.
+- Recorded the org control-plane architecture, including nested npm metadata pins, so agents reconstruct the lockfile trust boundary from the repo instead of private memory.
+- Made JavaScript lock evidence publication fail before mutation without descriptor/no-follow capabilities, create every output component from pinned directory descriptors, and roll back only inode-matched entries from a freshly owned project subtree after late write 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

@@ -64,7 +64,9 @@ Details: `README.md` and `PR_GOVERNANCE_AUDIT.md`.
 - `fuzz/` + `.clusterfuzzlite/` — Atheris fuzz targets for the review-output normalizer and the
   ClusterFuzzLite discovery marker.
 - `docs/` — master context, Project protocol, `org-required-workflow-rollout.md`,
-  `scorecard-governance.md`, SBOM inventory.
+  `scorecard-governance.md`, SBOM inventory. Doctoring records live under
+  `docs/doctoring/`. [`ARCHITECTURE.md`](ARCHITECTURE.md) is the control-plane
+  diagram for review, nested npm metadata pins, and merge trust boundaries.
 - `.jules/` — recorded performance (`bolt.md`) and security (`sentinel.md`) learnings from past work
   on `scripts/ci/`; worth scanning before optimizing or hardening those scripts.