chore(codeql): restack #2106 on protected main

.github/workflows/agent-review-runtime-quality-ci.yml

@@ -16,6 +16,8 @@ on:
       - ".github/workflows/opencode-review-dispatch.yml"
       - "scripts/ci/ensure_rust_llvm19.sh"
       - "tests/test_opencode_rust_coverage_toolchain_contract.py"
+      - "scripts/ci/materialize_base_javascript_packages.py"
+      - "tests/test_javascript_materializer_docstrings.py"
       - "tests/test_pr_review_autofix_nvidia_nim_contract.py"
       - "docs/doctoring/opencode-rust-coverage-runtime-boundary.md"
       - ".github/workflows/strix.yml"
@@ -185,6 +187,8 @@ jobs:
               .github/workflows/opencode-review-dispatch.yml|\
               scripts/ci/ensure_rust_llvm19.sh|\
               tests/test_opencode_rust_coverage_toolchain_contract.py|\
+              scripts/ci/materialize_base_javascript_packages.py|\
+              tests/test_javascript_materializer_docstrings.py|\
               docs/doctoring/opencode-rust-coverage-runtime-boundary.md)
                 opencode_suite=true
                 ;;
@@ -346,6 +350,13 @@ jobs:
           python -m pytest -q tests/test_opencode_rust_coverage_toolchain_contract.py
           python -m compileall -q tests/test_opencode_rust_coverage_toolchain_contract.py
 
+      - name: Verify JavaScript materializer documentation contract
+        if: steps.affected_suites.outputs.opencode == 'true'
+        run: |
+          set -euo pipefail
+          python -m pytest -q tests/test_javascript_materializer_docstrings.py
+          python -m compileall -q scripts/ci/materialize_base_javascript_packages.py tests/test_javascript_materializer_docstrings.py
+
       - name: Verify exact-head path policy and syntax
         if: steps.affected_suites.outputs.strix == 'true'
         env:
@@ -425,7 +436,8 @@ jobs:
         run: |
           python -m coverage run \
             --branch \
-            -m pytest --import-mode=importlib tests/test_organization_commercial_readiness_loop*.py -q
+            -m pytest --import-mode=importlib \
+            tests/test_organization_commercial_readiness_loop*.py -q
           python -m coverage report \
             --include='scripts/ci/organization_commercial_readiness_loop.py' \
             --show-missing \

CHANGELOG.d/20260912-javascript-materializer-docstrings.md

@@ -0,0 +1 @@
+Document trusted JavaScript lock discovery and validation boundaries with explanatory contracts enforced by CI.

docs/doctoring/org-queue-sweep-rotation.md

@@ -1,8 +1,16 @@
 # Org-queue-sweep review-dispatch rotation
 
+> **Superseded for queue hygiene.** The organization sweep no longer inventories
+> or cancels repository-wide queued/in-progress Actions runs. That duplicate
+> queue-hygiene path was removed by `.github#1878` (`1b65dbc35e7183722ad77894e2d80b39993be90d`),
+> and current-head coalescing was later integrated into the merge scheduler.
+> The rotation material below remains historical evidence for the former
+> review-dispatch fairness mechanism, not a description of current stale-run
+> ownership.
+
 ## Problem
 
-`org-queue-sweep` in `pr-review-merge-scheduler.yml` walks every organization
+Historically, `org-queue-sweep` in `pr-review-merge-scheduler.yml` walked every organization
 repository once per 15-minute tick and consumes bounded, organization-wide
 review-dispatch budgets across that entire walk. Default-base work uses
 `ORG_SWEEP_REVIEW_DISPATCH_LIMIT` (default `1`); stacked work uses the separate
@@ -23,6 +31,15 @@ required review.
 
 ## Decision
 
+The current ownership boundary is:
+
+- `pr-review-merge-scheduler` owns review, merge, and branch-update state.
+- The integrated current-head coalescer owns same-PR stale-run cleanup.
+- The organization sweep does not repeat an Actions inventory per repository.
+
+The rotation decision below is retained as historical operational evidence for
+the former review-dispatch fairness implementation.
+
 Rotate the sweep's repository walk order by a rotation index before applying
 the unchanged organization-wide budgets. `rotation_offset = rotation_index %
 repository_count`; the walk starts at that offset and wraps. This spreads each

scripts/ci/materialize_base_javascript_packages.py

@@ -58,7 +58,10 @@ def _github_actions_escape(value: object) -> str:
 
 
 def _git(repo_root: pathlib.Path, *args: str) -> bytes:
-    """Run one read-only git command in the materialized repository."""
+    """Run one read-only git command in the materialized repository.
+
+    Git failures remain bounded diagnostics and never become trusted input.
+    """
     completed = subprocess.run(
         ["git", "-C", str(repo_root), *args],
         check=False,
@@ -72,7 +75,10 @@ def _git(repo_root: pathlib.Path, *args: str) -> bytes:
 
 
 def _regular_base_paths(repo_root: pathlib.Path, base_sha: str) -> set[str]:
-    """Return regular blob paths from the exact validated base commit."""
+    """Return regular blob paths from the exact validated base commit.
+
+    Symlink-like and traversal paths are excluded before content is materialized.
+    """
     entries = _git(repo_root, "ls-tree", "-r", "-z", "--full-tree", base_sha)
     paths: set[str] = set()
     for raw_entry in entries.split(b"\0"):
@@ -102,7 +108,10 @@ def _regular_base_paths(repo_root: pathlib.Path, base_sha: str) -> set[str]:
 def base_pnpm_projects(
     repo_root: pathlib.Path, base_sha: str
 ) -> list[tuple[str, str, dict[str, bytes]]]:
-    """Return exact base pnpm inputs grouped by lockfile directory."""
+    """Return exact base pnpm inputs grouped by lockfile directory.
+
+    Each project must declare an exact package-manager version and regular inputs.
+    """
     if not SHA_RE.fullmatch(base_sha):
         raise ValueError("base SHA must be exactly 40 hexadecimal characters")
 
@@ -183,7 +192,10 @@ def base_pnpm_projects(
 def base_npm_projects(
     repo_root: pathlib.Path, base_sha: str
 ) -> list[tuple[str, str, dict[str, bytes]]]:
-    """Return exact base npm inputs grouped by lockfile directory."""
+    """Return exact base npm inputs grouped by lockfile directory.
+
+    Vestigial locks and unsafe workspace paths are excluded from the trusted set.
+    """
     if not SHA_RE.fullmatch(base_sha):
         raise ValueError("base SHA must be exactly 40 hexadecimal characters")
 
@@ -268,7 +280,10 @@ def base_npm_projects(
 
 
 def _lock_blob_sha(repo_root: pathlib.Path, revision_sha: str, lock_path: str) -> str:
-    """Return the exact Git blob SHA for one validated revision lockfile."""
+    """Return the exact Git blob SHA for one validated revision lockfile.
+
+    The identity binds materialized dependency bytes to the reviewed revision.
+    """
     raw_blob = _git(repo_root, "rev-parse", f"{revision_sha}:{lock_path}")
     blob_sha = raw_blob.decode("ascii", errors="strict").strip()
     if not SHA_RE.fullmatch(blob_sha):
@@ -279,7 +294,10 @@ def _lock_blob_sha(repo_root: pathlib.Path, revision_sha: str, lock_path: str) -
 
 
 def validate_head_npm_lock(lock_path: str, lock_content: bytes) -> None:
-    """Fail closed unless a changed HEAD npm lock is registry- and hash-bounded."""
+    """Fail closed unless a changed HEAD npm lock is registry- and hash-bounded.
+
+    Registry URLs, workspace links, and integrity values are checked without installation.
+    """
     try:
         lock_data: Any = json.loads(lock_content.decode("utf-8"))
     except (UnicodeDecodeError, json.JSONDecodeError) as exc:
@@ -372,7 +390,10 @@ def validate_head_npm_lock(lock_path: str, lock_content: bytes) -> None:
 def _validate_pnpm_tarball_url(
     lock_path: str, package_key: str, tarball_url: str
 ) -> None:
-    """Fail closed unless one pnpm tarball URL is an npm-registry HTTPS URL."""
+    """Fail closed unless one pnpm tarball URL is an npm-registry HTTPS URL.
+
+    Userinfo, ports, query strings, fragments, and alternate hosts are rejected.
+    """
     parsed = urllib.parse.urlsplit(tarball_url)
     try:
         parsed_port = parsed.port
@@ -516,7 +537,10 @@ def materialize(
     output_dir: pathlib.Path,
     head_sha: str | None = None,
 ) -> list[dict[str, str]]:
-    """Write trusted base and bounded HEAD inputs under Docker-context-safe paths."""
+    """Write trusted base and bounded HEAD inputs under Docker-context-safe paths.
+
+    Manifest records retain revision and lock-blob identity for downstream verification.
+    """
     if output_dir.exists() and output_dir.is_symlink():
         raise ValueError("output directory must not be a symlink")
     output_dir.mkdir(parents=True, exist_ok=True)
@@ -624,7 +648,10 @@ def materialize(
 
 
 def main(argv: list[str] | None = None) -> int:
-    """Materialize trusted JavaScript locks and report their exact revisions."""
+    """Materialize trusted JavaScript locks and report their exact revisions.
+
+    Invalid or unsafe input returns a bounded non-zero diagnostic for the caller.
+    """
     parser = argparse.ArgumentParser()
     parser.add_argument("--repo-root", required=True, type=pathlib.Path)
     parser.add_argument("--base-sha", required=True)

tests/test_javascript_materializer_docstrings.py

@@ -0,0 +1,21 @@
+"""Documentation contract for trusted JavaScript lock materialization."""
+
+import ast
+from pathlib import Path
+
+
+MODULE = Path(__file__).resolve().parents[1] / "scripts/ci/materialize_base_javascript_packages.py"
+
+
+def test_materializer_symbols_have_explanatory_multiline_docstrings() -> None:
+    """Lock discovery and validation code must explain its trust boundary."""
+    tree = ast.parse(MODULE.read_text(encoding="utf-8"))
+    violations = []
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        docstring = ast.get_docstring(node, clean=False)
+        if docstring is None or "\n" not in docstring:
+            violations.append((node.name, node.lineno))
+
+    assert not violations, f"materializer symbols need explanatory docs: {violations}"

tests/test_org_queue_sweep_documentation_contract.py

@@ -0,0 +1,17 @@
+"""Contract for the superseded organization queue-sweep runbook."""
+
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+RUNBOOK = ROOT / "docs" / "doctoring" / "org-queue-sweep-rotation.md"
+
+
+def test_runbook_marks_removed_queue_hygiene_as_historical() -> None:
+    """The runbook must not describe removed repository-wide inventory as current."""
+    source = RUNBOOK.read_text(encoding="utf-8")
+
+    assert "Superseded for queue hygiene" in source
+    assert "does not repeat an Actions inventory per repository" in source
+    assert "#1878" in source
+    assert "historical operational evidence" in source