From cf7a20ac94eccd8c3494c11661ccd69aa51c4cd6 Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Wed, 14 Oct 2026 20:56:41 +0300
Subject: [PATCH 1/4] ci: keep top-level workflow token permissions read-only

Code-scanning alert #178 (OpenSSF Scorecard Token-Permissions, topLevel):
scholarly-release-v1.yml granted contents, id-token and attestations write
at the workflow top level. A top-level grant applies to every job,
including any job added later, so it is never least privilege.
kernel-freshness.yml had the same defect with issues: write; Scorecard
does not report that one, but it is the same root cause.

Both workflows have exactly one job. The write grants move onto that job
(publish / freshness), and the top level becomes contents: read. Each
job's effective permissions are unchanged; only the default for any
future job is narrowed.

Add scripts/check-workflow-permissions.sh, run in CI by
scripts/check-workflow-permissions_test.sh:
- Every workflow must declare read-only top-level permissions.
- write-all is rejected.
- Every job-level write must be listed, with a justification, in
  scripts/workflow-write-permissions.allow.
- Stale allowlist entries fail, so the list cannot become a blanket
  exemption.

The suite fails against the workflows on main (802d515) and passes
after this change. It covers flow mappings, quoted values, an omitted
block, shorthands, an unlisted job grant and a grant moved to another job.

Signed-off-by: ErenAri <erenari27@gmail.com>
---
 .github/workflows/ci.yml                   |   5 +
 .github/workflows/kernel-freshness.yml     |   4 +-
 .github/workflows/scholarly-release-v1.yml |  12 +-
 scripts/check-workflow-permissions.sh      | 140 +++++++++++++
 scripts/check-workflow-permissions_test.sh | 230 +++++++++++++++++++++
 scripts/workflow-write-permissions.allow   |  33 +++
 6 files changed, 419 insertions(+), 5 deletions(-)
 create mode 100755 scripts/check-workflow-permissions.sh
 create mode 100755 scripts/check-workflow-permissions_test.sh
 create mode 100644 scripts/workflow-write-permissions.allow

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d8eb7881..104a4840 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -126,6 +126,11 @@ jobs:
         # Release-candidate canary observations must not span a runner-OS
         # migration of the moving ubuntu-latest label.
         run: bash scripts/canary-runner-pin_test.sh
+      - name: Workflow token-permission regression
+        # Top-level GITHUB_TOKEN permissions stay read-only and every job-level
+        # write grant is listed, with a justification, in
+        # scripts/workflow-write-permissions.allow.
+        run: bash scripts/check-workflow-permissions_test.sh
       - name: Coverage-floor regression
         run: bash scripts/check-coverage_test.sh
       - name: Release metadata consistency
diff --git a/.github/workflows/kernel-freshness.yml b/.github/workflows/kernel-freshness.yml
index 3bf535df..edd7ec63 100644
--- a/.github/workflows/kernel-freshness.yml
+++ b/.github/workflows/kernel-freshness.yml
@@ -24,7 +24,6 @@ on:
 
 permissions:
   contents: read
-  issues: write   # file/refresh/close the stale-baselines tracking issue
 
 concurrency:
   group: ${{ github.workflow }}
@@ -35,6 +34,9 @@ jobs:
     name: Baselines vs kernel-crawler
     runs-on: ubuntu-latest
     timeout-minutes: 15
+    permissions:
+      contents: read
+      issues: write   # file/refresh/close the stale-baselines tracking issue
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
diff --git a/.github/workflows/scholarly-release-v1.yml b/.github/workflows/scholarly-release-v1.yml
index c394f5d1..1677f569 100644
--- a/.github/workflows/scholarly-release-v1.yml
+++ b/.github/workflows/scholarly-release-v1.yml
@@ -6,11 +6,10 @@ on:
     paths:
       - ".github/workflows/scholarly-release-v1.yml"
 
+# Read-only by default; the one publish job holds the write grants
+# (scripts/check-workflow-permissions.sh).
 permissions:
-  contents: write
-  actions: read
-  id-token: write
-  attestations: write
+  contents: read
 
 concurrency:
   group: scholarly-release-v1
@@ -24,6 +23,11 @@ jobs:
     name: Publish immutable research v1 release
     runs-on: ubuntu-24.04
     timeout-minutes: 20
+    permissions:
+      contents: write      # create the research-v1 tag and release
+      actions: read        # download the pinned canonical source artifacts
+      id-token: write      # sign the archive provenance attestation
+      attestations: write  # store the archive provenance attestation
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
diff --git a/scripts/check-workflow-permissions.sh b/scripts/check-workflow-permissions.sh
new file mode 100755
index 00000000..02f4ba07
--- /dev/null
+++ b/scripts/check-workflow-permissions.sh
@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# Least-privilege GITHUB_TOKEN permissions for every workflow.
+#
+#   check-workflow-permissions.sh
+#
+# 1. Every workflow declares top-level `permissions:` and that block is
+#    read-only: `{}`, `read-all`, or a mapping whose values are all `read` or
+#    `none`. A top-level grant applies to every job, including jobs added
+#    later, so a write there is never least privilege (OpenSSF Scorecard
+#    Token-Permissions, topLevel).
+# 2. No job uses `write-all`.
+# 3. Every job-level `write` is listed in
+#    scripts/workflow-write-permissions.allow as
+#    `<workflow-file> <job-id> <permission> <justification...>`, so a new
+#    write grant needs a reviewed change to that file. An allowlist entry that
+#    no longer matches a grant fails too, so the list cannot drift into a
+#    blanket exemption.
+#
+# Overridable for the regression suite only: BPFCOMPAT_WORKFLOWS_DIR,
+# BPFCOMPAT_WORKFLOW_WRITE_ALLOWLIST.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+workflows_dir="${BPFCOMPAT_WORKFLOWS_DIR:-$ROOT/.github/workflows}"
+allowlist="${BPFCOMPAT_WORKFLOW_WRITE_ALLOWLIST:-$ROOT/scripts/workflow-write-permissions.allow}"
+
+[[ -d "$workflows_dir" ]] || { echo "[workflow-permissions] missing workflows dir: $workflows_dir" >&2; exit 2; }
+[[ -f "$allowlist" ]] || { echo "[workflow-permissions] missing allowlist: $allowlist" >&2; exit 2; }
+
+python3 - "$workflows_dir" "$allowlist" <<'PY'
+import os
+import sys
+
+import yaml
+
+workflows_dir, allowlist_path = sys.argv[1], sys.argv[2]
+READ_ONLY = {"read", "none"}
+failures = []
+
+
+class StrictLoader(yaml.SafeLoader):
+    """SafeLoader that rejects duplicate mapping keys instead of keeping the last."""
+
+
+def _no_duplicates(loader, node, deep=False):
+    seen = set()
+    for key_node, _ in node.value:
+        key = loader.construct_object(key_node, deep=deep)
+        if key in seen:
+            raise yaml.constructor.ConstructorError(
+                None, None, f"duplicate key {key!r}", key_node.start_mark)
+        seen.add(key)
+    return yaml.SafeLoader.construct_mapping(loader, node, deep=deep)
+
+
+StrictLoader.add_constructor(
+    yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _no_duplicates)
+
+
+def fail(msg):
+    failures.append(msg)
+    print(f"[workflow-permissions] FAIL: {msg}", file=sys.stderr)
+
+
+allowed = set()
+with open(allowlist_path, encoding="utf-8") as handle:
+    for lineno, raw in enumerate(handle, 1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split(None, 3)
+        if len(parts) < 4 or not parts[3].strip():
+            fail(f"{allowlist_path}:{lineno}: expected '<workflow> <job> <permission> <justification>'")
+            continue
+        key = tuple(parts[:3])
+        if key in allowed:
+            fail(f"{allowlist_path}:{lineno}: duplicate entry {' '.join(key)}")
+        allowed.add(key)
+
+granted = set()
+files = sorted(
+    f for f in os.listdir(workflows_dir) if f.lower().endswith((".yml", ".yaml"))
+)
+if not files:
+    fail(f"no workflow files under {workflows_dir}")
+
+for name in files:
+    path = os.path.join(workflows_dir, name)
+    with open(path, encoding="utf-8") as handle:
+        try:
+            wf = yaml.load(handle, Loader=StrictLoader)
+        except yaml.YAMLError as err:
+            fail(f"{name}: invalid or ambiguous YAML: {err}")
+            continue
+    if not isinstance(wf, dict):
+        fail(f"{name}: not a workflow mapping")
+        continue
+
+    if "permissions" not in wf:
+        fail(f"{name}: no top-level permissions; the default token may be read-write")
+    else:
+        top = wf["permissions"]
+        if top in ({}, "read-all"):
+            pass
+        elif isinstance(top, dict):
+            for perm, level in top.items():
+                if str(level) not in READ_ONLY:
+                    fail(f"{name}: top-level permission '{perm}: {level}' grants write to every job; move it to the job that needs it")
+        else:
+            fail(f"{name}: top-level permissions '{top}' is not read-only ({{}}, read-all, or read/none values)")
+
+    for job_id, job in (wf.get("jobs") or {}).items():
+        if not isinstance(job, dict) or "permissions" not in job:
+            continue
+        perms = job["permissions"]
+        if perms in ({}, "read-all"):
+            continue
+        if not isinstance(perms, dict):
+            fail(f"{name}/{job_id}: job permissions '{perms}' is not allowed (write-all and other shorthands are rejected)")
+            continue
+        for perm, level in perms.items():
+            level = str(level)
+            if level in READ_ONLY:
+                continue
+            if level != "write":
+                fail(f"{name}/{job_id}: unknown permission level '{perm}: {level}'")
+                continue
+            key = (name, str(job_id), str(perm))
+            granted.add(key)
+            if key not in allowed:
+                fail(f"{name}/{job_id}: job-level '{perm}: write' is not in {os.path.basename(allowlist_path)}")
+
+for key in sorted(allowed - granted):
+    fail(f"stale allowlist entry (no such job-level write grant): {' '.join(key)}")
+
+if failures:
+    print(f"[workflow-permissions] {len(failures)} failure(s)", file=sys.stderr)
+    sys.exit(1)
+print(f"[workflow-permissions] PASS: {len(files)} workflows, top-level read-only, {len(granted)} allowlisted job-level write grant(s)")
+PY
diff --git a/scripts/check-workflow-permissions_test.sh b/scripts/check-workflow-permissions_test.sh
new file mode 100755
index 00000000..ff2e3a26
--- /dev/null
+++ b/scripts/check-workflow-permissions_test.sh
@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# Regression suite for scripts/check-workflow-permissions.sh.
+#
+# The real repository must pass. Each fixture below must be rejected: they
+# are the ways a write-scoped GITHUB_TOKEN can reach jobs that never asked for
+# it (top-level grants, shorthands, an omitted block) or slip past review
+# (an unlisted job grant, a stale allowlist entry).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+script="$ROOT/scripts/check-workflow-permissions.sh"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+bash "$script" >"$tmp/real.log"
+grep -Fq 'PASS' "$tmp/real.log"
+echo "ok:   repository workflows pass"
+
+allow="$tmp/allow"
+cat >"$allow" <<'EOF'
+# fixture allowlist
+w.yml build packages push the image
+EOF
+
+# check <expect pass|fail> <description> [reason] [file-name]; reads the
+# fixture workflow from stdin. A rejected fixture must be rejected for the
+# stated reason, so an unrelated failure or a crash cannot pass for one.
+check() {
+  local expect="$1" desc="$2" reason="${3:-}" file="${4:-w.yml}"
+  rm -rf "$tmp/wf"; mkdir -p "$tmp/wf"
+  cat >"$tmp/wf/$file"
+  if BPFCOMPAT_WORKFLOWS_DIR="$tmp/wf" BPFCOMPAT_WORKFLOW_WRITE_ALLOWLIST="$allow" \
+    bash "$script" >"$tmp/out.log" 2>&1; then
+    got=pass
+  else
+    got=fail
+  fi
+  if [[ "$got" != "$expect" ]]; then
+    echo "FAIL: ${desc}: expected ${expect}, got ${got}" >&2
+    cat "$tmp/out.log" >&2
+    exit 1
+  fi
+  if [[ -n "$reason" ]] && ! grep -Fq -- "$reason" "$tmp/out.log"; then
+    echo "FAIL: ${desc}: rejected, but not for: ${reason}" >&2
+    cat "$tmp/out.log" >&2
+    exit 1
+  fi
+  echo "ok:   ${desc} -> ${expect}"
+}
+
+base_job='jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - run: true'
+
+check pass "read-only top level with allowlisted job write" <<EOF
+on: push
+permissions:
+  contents: read
+$base_job
+EOF
+
+check pass "empty top-level permissions" <<EOF
+on: push
+permissions: {}
+$base_job
+EOF
+
+check pass "read-all top level" <<EOF
+on: push
+permissions: read-all
+$base_job
+EOF
+
+check fail "top-level contents: write" "grants write to every job" <<EOF
+on: push
+permissions:
+  contents: write
+$base_job
+EOF
+
+check fail "top-level write hidden among reads" "grants write to every job" <<EOF
+on: push
+permissions:
+  contents: read
+  actions: read
+  id-token: write
+$base_job
+EOF
+
+check fail "top-level flow-mapping write" "grants write to every job" <<EOF
+on: push
+permissions: {contents: read, issues: write}
+$base_job
+EOF
+
+check fail "top-level quoted write" "grants write to every job" <<EOF
+on: push
+permissions:
+  contents: "write"
+$base_job
+EOF
+
+check fail "top-level write-all" "is not read-only" <<EOF
+on: push
+permissions: write-all
+$base_job
+EOF
+
+check fail "missing top-level permissions" "no top-level permissions" <<EOF
+on: push
+$base_job
+EOF
+
+check fail "unknown top-level shorthand" "is not read-only" <<EOF
+on: push
+permissions: admin
+$base_job
+EOF
+
+check fail "job-level write-all" "is not allowed" <<'EOF'
+on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions: write-all
+    steps:
+      - run: true
+EOF
+
+check fail "job-level write not in the allowlist" "'contents: write' is not in" <<'EOF'
+on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      packages: write
+      contents: write
+    steps:
+      - run: true
+EOF
+
+check fail "allowlisted permission granted on a different job" "w.yml/other: job-level 'packages: write' is not in" <<'EOF'
+on: push
+permissions:
+  contents: read
+jobs:
+  other:
+    runs-on: ubuntu-24.04
+    permissions:
+      packages: write
+    steps:
+      - run: true
+EOF
+
+check fail "stale allowlist entry (grant removed)" "stale allowlist entry" <<'EOF'
+on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    steps:
+      - run: true
+EOF
+
+check fail "duplicate permission key (write then read)" "duplicate key" <<EOF
+on: push
+permissions:
+  contents: write
+  contents: read
+$base_job
+EOF
+
+check fail "duplicate top-level permissions block" "duplicate key" <<EOF
+on: push
+permissions: write-all
+permissions: {}
+$base_job
+EOF
+
+check fail "uppercase .YML extension is scanned" "grants write to every job" evil.YML <<EOF
+on: push
+permissions:
+  contents: write
+$base_job
+EOF
+
+check fail "capitalised Write level" "unknown permission level" <<'EOF'
+on: push
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      packages: Write
+    steps:
+      - run: true
+EOF
+
+# The strict loader is a SafeLoader: python tags are refused, never executed.
+check fail "python object tag is refused" "invalid or ambiguous YAML" <<EOF
+on: push
+permissions: !!python/object/apply:os.system ["touch $tmp/pwned"]
+$base_job
+EOF
+if [[ -e "$tmp/pwned" ]]; then
+  echo "FAIL: a python tag in a workflow was executed" >&2
+  exit 1
+fi
+
+# An allowlist line without a justification is rejected.
+printf 'w.yml build packages\n' >"$allow"
+check fail "allowlist entry without justification" "expected '<workflow> <job> <permission> <justification>'" <<EOF
+on: push
+permissions:
+  contents: read
+$base_job
+EOF
+
+echo "check-workflow-permissions_test: all checks passed"
diff --git a/scripts/workflow-write-permissions.allow b/scripts/workflow-write-permissions.allow
new file mode 100644
index 00000000..997cfedf
--- /dev/null
+++ b/scripts/workflow-write-permissions.allow
@@ -0,0 +1,33 @@
+# Job-level GITHUB_TOKEN write grants, enforced by
+# scripts/check-workflow-permissions.sh. Each line:
+#   <workflow-file> <job-id> <permission> <justification>
+# Adding a write grant to a workflow requires a reviewed entry here; an entry
+# that no longer matches a grant fails the check. Top-level write grants are
+# never allowed.
+codeql.yml analyze security-events upload CodeQL SARIF to code scanning
+compatibility-matrix-publish.yml publish-compatibility-matrix pages deploy the compatibility site to GitHub Pages
+compatibility-matrix-publish.yml publish-compatibility-matrix id-token OIDC token for the Pages deployment
+external-consumer-canary.yml report issues file the external-consumer canary failure issue
+ghcr-image.yml image packages push the main-branch image to GHCR
+latest-kernel-compatibility.yml latest-kernel-sweep id-token sign the campaign evidence attestation
+latest-kernel-compatibility.yml latest-kernel-sweep attestations store the campaign evidence attestation
+maintenance-evidence.yml attest id-token sign the maintenance evidence attestation
+maintenance-evidence.yml attest attestations store the maintenance evidence attestation
+promote-release.yml promote contents publish the verified draft release (production-release environment, tag-only, 15-minute wait)
+promote-release.yml promote packages write the promoted release image tag to GHCR (production-release environment)
+release-artifacts.yml build-and-sign id-token keyless cosign signing and build provenance
+release-artifacts.yml build-and-sign attestations store build provenance and SBOM attestations
+release-artifacts.yml build-candidate-image packages push the candidate image to GHCR
+release-artifacts.yml build-candidate-image id-token keyless cosign signing of the candidate image
+release-artifacts.yml build-candidate-image attestations store the candidate image provenance attestation
+release-artifacts.yml assemble-candidate-evidence id-token sign the candidate evidence attestation
+release-artifacts.yml assemble-candidate-evidence attestations store the candidate evidence attestation
+release-artifacts.yml stage-draft-release contents create the private draft release (tag builds only)
+release-candidate-canary.yml external-consumers actions dispatch external-consumer-canary at the immutable RC tag
+rollback-drill.yml rollback packages move the drill-only rollback alias (production-drill environment, main only)
+scholarly-release-v1.yml publish contents create the one-time research-v1 tag and release (refuses if either exists)
+scholarly-release-v1.yml publish id-token sign the research archive provenance attestation
+scholarly-release-v1.yml publish attestations store the research archive provenance attestation
+scorecard.yml analysis security-events upload Scorecard SARIF to code scanning
+scorecard.yml analysis id-token publish results to the Scorecard API
+kernel-freshness.yml freshness issues file, refresh and close the stale-baselines tracking issue

From 1daeb1535e201bbebe16b72930201b307bfa6e7f Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Wed, 14 Oct 2026 21:12:19 +0300
Subject: [PATCH 2/4] ci: never re-attempt the published research-v1 release

scholarly-release-v1 runs on every push to main that changes its own
file. research-v1 was published once, from 141c491 on 2026-09-19 (run
35456618576). Any later edit, including the permission fix in this PR,
re-ran the publish job with a contents:write token. Its own refusal step
stopped it, but the run went red.

A read-only `state` job (contents/attestations read) now runs
scripts/research/research-v1-release-state.sh before anything else, and
the write-scoped `publish` job runs only on
`needs.state.outputs.publish == 'true'`:

- publish=true only when neither the tag nor the release exists AND the
  run is the pinned commit 141c491. That is the original first
  publication, which can no longer happen.
- publish=false only when the published release is verified intact. The
  annotated tag (direct and peeled refs) peels to 141c491. The release is non-draft and
  non-prerelease with exactly the four assets. archive-lock.json is
  byte-identical to the reviewed lock. The manifest and payload match
  the lock. RELEASE-CHECKSUMS.txt covers exactly the other three files
  and verifies. All four assets carry a scholarly-release-v1.yml
  attestation for 141c491 on refs/heads/main. The run ends green with no
  write token issued.
- Every other state fails closed and never silently skips: a missing
  release run from another commit (which would create a different
  research-v1), a partial publication, a mismatch, or a lookup error.

scripts/check-release-consistency.sh now requires this gate: the pinned
commit, the state script, `needs: state`, the exact `if:` and a
read-only state job. It rejects the ungated workflow from cf7a20a.

Tests:
- scripts/research/test-release-state-v1.sh (real git remote, stubbed
  gh) has 30 checks, each asserting the failure reason.
- Every guard mutation is caught except dropping the payload size check.
  That one is equivalent, since the payload SHA-256 binding implies size.
- Against the live release, the script returns publish=false from
  802d515 and fails for a wrong pinned commit.

docs/workflow-token-permissions.md records the Scorecard v5.5.0 scoring
rules, reproduces alerts #173-#178 locally on 802d515 (0 SARIF results
on this tree, score 10), and documents the five required job-level
write grants with the step that uses each and its gate.

Signed-off-by: ErenAri <erenari27@gmail.com>
---
 .github/workflows/ci.yml                      |   4 +
 .github/workflows/scholarly-release-v1.yml    |  35 ++++
 docs/workflow-token-permissions.md            |  67 +++++++
 scripts/check-release-consistency.sh          |  25 ++-
 scripts/check-release-consistency_test.sh     |  22 ++
 scripts/research/research-v1-release-state.sh | 151 ++++++++++++++
 scripts/research/test-release-state-v1.sh     | 188 ++++++++++++++++++
 7 files changed, 491 insertions(+), 1 deletion(-)
 create mode 100644 docs/workflow-token-permissions.md
 create mode 100755 scripts/research/research-v1-release-state.sh
 create mode 100755 scripts/research/test-release-state-v1.sh

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 104a4840..d6d152a9 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -131,6 +131,10 @@ jobs:
         # write grant is listed, with a justification, in
         # scripts/workflow-write-permissions.allow.
         run: bash scripts/check-workflow-permissions_test.sh
+      - name: Research v1 release-state regression
+        # scholarly-release-v1 re-runs on edits to itself; the immutable,
+        # already-published research-v1 must be verified, never re-attempted.
+        run: bash scripts/research/test-release-state-v1.sh
       - name: Coverage-floor regression
         run: bash scripts/check-coverage_test.sh
       - name: Release metadata consistency
diff --git a/.github/workflows/scholarly-release-v1.yml b/.github/workflows/scholarly-release-v1.yml
index 1677f569..956996b3 100644
--- a/.github/workflows/scholarly-release-v1.yml
+++ b/.github/workflows/scholarly-release-v1.yml
@@ -17,10 +17,45 @@ concurrency:
 
 env:
   RESEARCH_TAG: research-v1
+  # research-v1 was published from this commit on 2026-09-19 (run 35456618576).
+  # It is immutable: the release is never re-created from any other commit.
+  RESEARCH_COMMIT: 141c491bd1508600338e7bc27abbc5a117eb7508
 
 jobs:
+  # This workflow re-runs whenever its own file changes on main. A read-only
+  # job first establishes the publication state; the write-scoped publish job
+  # runs only for the original first publication. An intact, verified
+  # research-v1 ends the run green without a write token; a missing, partial
+  # or mismatched one fails here (scripts/research/research-v1-release-state.sh).
+  state:
+    name: Verify research v1 publication state
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      attestations: read
+    outputs:
+      publish: ${{ steps.state.outputs.publish }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Establish research v1 state
+        id: state
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          bash scripts/research/research-v1-release-state.sh \
+            "${GITHUB_REPOSITORY}" "${RESEARCH_TAG}" "${RESEARCH_COMMIT}" \
+            research/archive/v1/archive-lock.json "${RUNNER_TEMP}/research-v1-state" \
+            >>"$GITHUB_OUTPUT"
+
   publish:
     name: Publish immutable research v1 release
+    needs: state
+    if: needs.state.outputs.publish == 'true'
     runs-on: ubuntu-24.04
     timeout-minutes: 20
     permissions:
diff --git a/docs/workflow-token-permissions.md b/docs/workflow-token-permissions.md
new file mode 100644
index 00000000..a4aca131
--- /dev/null
+++ b/docs/workflow-token-permissions.md
@@ -0,0 +1,67 @@
+# Workflow token permissions
+
+Every workflow in `.github/workflows` declares read-only top-level
+`permissions`. Write access to `GITHUB_TOKEN` is granted only at the job that
+uses it. `scripts/check-workflow-permissions.sh` enforces both rules in CI
+(`scripts/check-workflow-permissions_test.sh`):
+
+- a top-level write, `write-all`, or a missing top-level block fails;
+- a job-level write must be listed, with a justification, in
+  `scripts/workflow-write-permissions.allow`;
+- an allowlist entry that no longer matches a grant fails.
+
+## How OpenSSF Scorecard scores this (v5.5.0)
+
+The `Token-Permissions` check (`checks/evaluation/permissions.go`) treats the
+two levels differently:
+
+- A **top-level** `contents`, `packages` or `actions` write lowers the check
+  score by 10, i.e. to 0.
+- A **job-level** write is logged as a warning. It lowers the score only when
+  the same workflow also has a top-level write, or declares no top-level
+  permissions.
+
+The SARIF output that becomes code-scanning alerts (`pkg/scorecard/sarif.go`)
+skips a check whose score meets the policy minimum. Below it, every warning
+becomes an alert carrying the check score. That is why one top-level grant in
+`scholarly-release-v1.yml` (alert #178) also turned the five required
+job-level grants into "score is 0" alerts (#173–#177).
+
+The same v5.5.0 binary was run locally (`--local`, `--checks
+Token-Permissions`, policy minimum 10):
+- on main `802d515` it reproduces exactly alerts #173–#178;
+- on the read-only-top-level tree it scores 10 and emits no SARIF results.
+
+The job-level warnings are still present in `--show-details` output. They
+describe the required grants below.
+
+## Required job-level write grants
+
+These are the five write grants Scorecard reported (#173–#177). Each is
+limited to the one job that uses it and is not dismissed.
+
+| Alert | Workflow / job | Grant | Used by | Gate |
+|---|---|---|---|---|
+| #173 | `promote-release.yml` / `promote` | `contents: write` | `scripts/promote-release.sh` `gh release edit` publishes the verified draft | `production-release` environment: `v*` tags only, 15-minute wait, no admin bypass; exact candidate run, commit and digest inputs plus typed confirmation |
+| #174 | `promote-release.yml` / `promote` | `packages: write` | `scripts/promote-release.sh` `docker buildx imagetools create` writes the promoted image tag | same environment and inputs as #173; digest verified by cosign before promotion |
+| #175 | `release-artifacts.yml` / `stage-draft-release` | `contents: write` | `softprops/action-gh-release` creates a **draft** release (`draft: true`, `make_latest: false`) | `if: startsWith(github.ref, 'refs/tags/v')`; tags are immutable (ruleset); publication still requires #173 |
+| #176 | `release-candidate-canary.yml` / `external-consumers` | `actions: write` | `gh workflow run external-consumer-canary.yml` at the immutable RC tag | needs the planning job's observation window; dispatch only, no contents or packages write |
+| #177 | `rollback-drill.yml` / `rollback` | `packages: write` | `docker buildx imagetools create` moves the drill-only `rollback-drill-*` alias | `production-drill` environment; `GITHUB_REF` must be `refs/heads/main`; `latest` proven unchanged |
+
+`release-candidate-canary.yml` (#176) produces the v0.4.0 release-candidate
+evidence, so it is not changed while a qualification window is open. A
+reusable-workflow call could replace the dispatch and drop `actions: write`.
+That would change the evidence contract (`external_consumer_run_id`), so it
+belongs after graduation.
+
+## research-v1
+
+`scholarly-release-v1.yml` runs on every push that changes its own file.
+`research-v1` was published once, from `141c491`, and is immutable.
+
+A read-only `state` job (`scripts/research/research-v1-release-state.sh`)
+decides whether the write-scoped `publish` job may run:
+- **publish** only for the original first publication from the pinned commit;
+- **skip, green** only when the published tag, release, assets, lock,
+  checksums and attestations all verify;
+- **fail** in every other case, never a silent skip.
diff --git a/scripts/check-release-consistency.sh b/scripts/check-release-consistency.sh
index c9a7d9da..8f570378 100755
--- a/scripts/check-release-consistency.sh
+++ b/scripts/check-release-consistency.sh
@@ -125,10 +125,33 @@ for required_control in \
   'Create annotated research tag' \
   'Publish GitHub research release' \
   '--verify-tag' \
-  '--latest=false'; do
+  '--latest=false' \
+  'RESEARCH_COMMIT: 141c491bd1508600338e7bc27abbc5a117eb7508' \
+  'bash scripts/research/research-v1-release-state.sh' \
+  'needs: state' \
+  "if: needs.state.outputs.publish == 'true'"; do
   grep -Fq -- "$required_control" "$scholarly_workflow" ||
     fail "$scholarly_workflow is missing required control: $required_control"
 done
+# research-v1 is published and immutable: a re-run must not reach the
+# write-scoped publish job unless the read-only state job says so.
+python3 - "$scholarly_workflow" <<'PY' ||
+import sys
+import yaml
+
+wf = yaml.safe_load(open(sys.argv[1], encoding="utf-8"))
+jobs = wf.get("jobs") or {}
+publish = jobs.get("publish") or {}
+state = jobs.get("state") or {}
+ok = (
+    set(jobs) == {"state", "publish"}
+    and publish.get("needs") == "state"
+    and publish.get("if") == "needs.state.outputs.publish == 'true'"
+    and all(str(v) in ("read", "none") for v in (state.get("permissions") or {"x": "write"}).values())
+)
+sys.exit(0 if ok else 1)
+PY
+  fail "$scholarly_workflow publish job must be gated by the read-only state job (needs: state, if: needs.state.outputs.publish == 'true')"
 if grep -Eq 'workflow_dispatch:|refs/tags/v|tags:[[:space:]]*\[.*v\*|scripts/promote-release\.sh|softprops/action-gh-release@|value=latest' "$scholarly_workflow"; then
   fail "$scholarly_workflow must remain isolated from product release/promotion paths"
 fi
diff --git a/scripts/check-release-consistency_test.sh b/scripts/check-release-consistency_test.sh
index 45288e81..b0c907df 100755
--- a/scripts/check-release-consistency_test.sh
+++ b/scripts/check-release-consistency_test.sh
@@ -91,6 +91,28 @@ if BPFCOMPAT_RELEASE_METADATA=release.yaml \
 fi
 cp "$tmp/scholarly-release-v1.yml" "$scholarly_workflow"
 
+# Each broken state gate must be rejected for the gate, not by accident.
+while IFS='|' read -r gate_mutation gate_reason; do
+  sed -i "$gate_mutation" "$scholarly_workflow"
+  if BPFCOMPAT_RELEASE_METADATA=release.yaml \
+    "$script" >"$tmp/bad-scholarly-gate.log" 2>&1; then
+    echo "[release-consistency-test] accepted scholarly workflow with a broken state gate: ${gate_mutation}" >&2
+    exit 1
+  fi
+  if ! grep -Fq -- "$gate_reason" "$tmp/bad-scholarly-gate.log"; then
+    echo "[release-consistency-test] broken state gate rejected for the wrong reason: ${gate_mutation}" >&2
+    cat "$tmp/bad-scholarly-gate.log" >&2
+    exit 1
+  fi
+  cp "$tmp/scholarly-release-v1.yml" "$scholarly_workflow"
+done <<'MUTATIONS'
+/if: needs.state.outputs.publish == 'true'/d|missing required control: if: needs.state.outputs.publish == 'true'
+/^    needs: state$/d|missing required control: needs: state
+s/^      attestations: read$/      contents: write/|must be gated by the read-only state job
+s/^  state:$/  status:/|must be gated by the read-only state job
+/RESEARCH_COMMIT: 141c491/d|missing required control: RESEARCH_COMMIT
+MUTATIONS
+
 sed -i '/--latest=false/d' "$scholarly_workflow"
 if BPFCOMPAT_RELEASE_METADATA=release.yaml \
   "$script" >"$tmp/bad-scholarly-latest.log" 2>&1; then
diff --git a/scripts/research/research-v1-release-state.sh b/scripts/research/research-v1-release-state.sh
new file mode 100755
index 00000000..89aac9a1
--- /dev/null
+++ b/scripts/research/research-v1-release-state.sh
@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+# Decide, read-only, whether scholarly-release-v1 may publish research-v1.
+#
+#   research-v1-release-state.sh <repository> <tag> <pinned-commit> <archive-lock.json> <work-dir>
+#
+# research-v1 is a one-time, immutable research release, created from
+# <pinned-commit>. The workflow re-runs whenever its own file changes on main,
+# so it must never re-attempt that publication from a later commit. Prints
+# exactly one line on stdout, for $GITHUB_OUTPUT:
+#
+#   publish=true   neither the tag nor the release exists AND this run is the
+#                  pinned commit (the original first publication);
+#   publish=false  the tag and the release both exist and the release is
+#                  verified intact:
+#                    - the tag peels to the pinned commit;
+#                    - the release is a non-draft, non-prerelease release
+#                      with exactly the four archive assets;
+#                    - archive-lock.json is byte-identical to the reviewed
+#                      lock;
+#                    - the manifest and payload ZIP match the lock;
+#                    - RELEASE-CHECKSUMS.txt covers exactly the other three
+#                      assets and verifies;
+#                    - every asset carries a scholarly-release-v1.yml
+#                      attestation for the pinned commit on refs/heads/main.
+#
+# Everything else exits non-zero:
+#   - a tag without a release, or a release without a tag;
+#   - a mismatched or incomplete release;
+#   - a missing release while running from any other commit, which would
+#     create a *different* research-v1;
+#   - any lookup that could not be completed.
+# Nothing is ever skipped silently.
+#
+# Environment: GITHUB_SHA (the commit under test). Overridable for the
+# regression suite only: BPFCOMPAT_RESEARCH_REMOTE (git remote used to peel
+# the tag).
+set -euo pipefail
+
+[[ "$#" -eq 5 ]] || { echo "usage: $0 <repository> <tag> <pinned-commit> <archive-lock.json> <work-dir>" >&2; exit 2; }
+repo="$1"; tag="$2"; pinned="$3"; lock="$4"; work="$5"
+remote="${BPFCOMPAT_RESEARCH_REMOTE:-https://github.com/${repo}.git}"
+head_sha="${GITHUB_SHA:-}"
+
+fail() {
+  echo "::error title=research-v1 release state::$*" >&2
+  exit 1
+}
+
+[[ "$pinned" =~ ^[0-9a-f]{40}$ ]] || fail "pinned commit is not a full SHA: ${pinned}"
+[[ "$head_sha" =~ ^[0-9a-f]{40}$ ]] || fail "GITHUB_SHA is not a full SHA: '${head_sha}'"
+[[ -f "$lock" ]] || fail "missing archive lock: ${lock}"
+mkdir -p -- "$work"
+
+# Tag: found / absent / error, never guessed.
+set +e
+refs="$(git ls-remote --exit-code --tags "$remote" "refs/tags/${tag}" "refs/tags/${tag}^{}" 2>/dev/null)"
+rc=$?
+set -e
+tag_commit=""
+if [[ "$rc" -eq 2 && -z "$refs" ]]; then
+  tag_state=absent
+elif [[ "$rc" -eq 0 && -n "$refs" ]]; then
+  tag_state=found
+  direct=""; peeled=""
+  while IFS=$'\t' read -r sha ref; do
+    [[ "$sha" =~ ^[0-9a-f]{40}$ ]] || fail "malformed ls-remote answer for ${tag}"
+    case "$ref" in
+      "refs/tags/${tag}^{}") peeled="$sha" ;;
+      "refs/tags/${tag}") direct="$sha" ;;
+      *) fail "unexpected ref in ls-remote answer: ${ref}" ;;
+    esac
+  done <<<"$refs"
+  # research-v1 was created annotated; a lightweight tag is not that tag.
+  [[ -n "$peeled" ]] || fail "${tag} is not an annotated tag"
+  [[ -n "$direct" ]] || fail "ls-remote answered only the peeled ref for ${tag}"
+  tag_commit="$peeled"
+else
+  fail "could not query tag ${tag} on ${remote} (exit ${rc})"
+fi
+
+# Release: found / absent / error. Only gh's explicit "release not found"
+# counts as absent; any other failure is an error.
+set +e
+release_json="$(gh release view "$tag" --repo "$repo" --json tagName,isDraft,isPrerelease,assets 2>"$work/release.err")"
+rc=$?
+set -e
+if [[ "$rc" -eq 0 ]]; then
+  release_state=found
+elif grep -Fqx 'release not found' "$work/release.err"; then
+  release_state=absent
+else
+  fail "could not query release ${tag}: $(head -c 300 "$work/release.err")"
+fi
+rm -f "$work/release.err"
+
+case "${tag_state}/${release_state}" in
+  absent/absent)
+    [[ "$head_sha" == "$pinned" ]] ||
+      fail "${tag} is missing, but it is pinned to ${pinned}; publishing from ${head_sha} would create a different ${tag}. Investigate; it is never re-created automatically"
+    echo "research-v1 state: first publication from the pinned commit" >&2
+    echo "publish=true"
+    exit 0
+    ;;
+  found/found) ;;
+  found/absent) fail "${tag} tag exists without its release (incomplete publication)" ;;
+  absent/found) fail "${tag} release exists without its tag (incomplete publication)" ;;
+esac
+
+[[ "$tag_commit" == "$pinned" ]] || fail "${tag} peels to ${tag_commit}, expected ${pinned}"
+
+expected_assets='["RELEASE-CHECKSUMS.txt","archive-lock.json","archive-manifest.json","bpfcompat-research-v1-payload.zip"]'
+jq -e --arg tag "$tag" --argjson assets "$expected_assets" '
+  .tagName == $tag and .isDraft == false and .isPrerelease == false and
+  ([.assets[].name] | sort) == $assets
+' <<<"$release_json" >/dev/null ||
+  fail "${tag} release is not the published four-asset research release: $(jq -c '{tagName,isDraft,isPrerelease,assets:[.assets[].name]}' <<<"$release_json" 2>/dev/null)"
+
+dl="$work/assets"
+rm -rf -- "$dl"; mkdir -p -- "$dl"
+gh release download "$tag" --repo "$repo" --dir "$dl" || fail "could not download ${tag} assets"
+[[ "$(cd "$dl" && find . -maxdepth 1 -type f -printf '%f\n' | sort | jq -Rsc 'split("\n") | map(select(length > 0)) | sort')" == "$expected_assets" ]] ||
+  fail "downloaded ${tag} assets do not match the expected four files"
+
+cmp -s -- "$dl/archive-lock.json" "$lock" || fail "${tag} archive-lock.json differs from the reviewed ${lock}"
+
+sha() { sha256sum -- "$1" | awk '{print $1}'; }
+jq -e \
+  --arg manifest "sha256:$(sha "$dl/archive-manifest.json")" \
+  --arg payload "sha256:$(sha "$dl/bpfcompat-research-v1-payload.zip")" \
+  --argjson size "$(stat -c %s -- "$dl/bpfcompat-research-v1-payload.zip")" '
+    .manifest.sha256 == $manifest and
+    .payload_zip.sha256 == $payload and
+    .payload_zip.size_bytes == $size
+  ' "$lock" >/dev/null || fail "${tag} manifest or payload ZIP does not match the archive lock"
+
+[[ "$(awk '{print $2}' "$dl/RELEASE-CHECKSUMS.txt" | sort | tr '\n' ' ')" == "archive-lock.json archive-manifest.json bpfcompat-research-v1-payload.zip " ]] ||
+  fail "${tag} RELEASE-CHECKSUMS.txt does not list exactly the three archive files"
+(cd "$dl" && sha256sum --quiet --strict -c RELEASE-CHECKSUMS.txt) >&2 ||
+  fail "${tag} RELEASE-CHECKSUMS.txt does not verify"
+
+for asset in archive-lock.json archive-manifest.json bpfcompat-research-v1-payload.zip RELEASE-CHECKSUMS.txt; do
+  gh attestation verify "$dl/$asset" \
+    --repo "$repo" \
+    --signer-workflow "${repo}/.github/workflows/scholarly-release-v1.yml" \
+    --source-digest "$pinned" \
+    --source-ref refs/heads/main >/dev/null ||
+    fail "${tag} ${asset} has no scholarly-release-v1.yml attestation for ${pinned}"
+done
+
+echo "research-v1 state: already published at ${pinned} and verified intact; not re-publishing" >&2
+echo "publish=false"
diff --git a/scripts/research/test-release-state-v1.sh b/scripts/research/test-release-state-v1.sh
new file mode 100755
index 00000000..202983d9
--- /dev/null
+++ b/scripts/research/test-release-state-v1.sh
@@ -0,0 +1,188 @@
+#!/usr/bin/env bash
+# Regression suite for scripts/research/research-v1-release-state.sh.
+#
+# Real git (a local remote with a real annotated research-v1 tag); `gh` is a
+# stub serving a fixture release and logging attestation calls. Each case
+# changes one fact. A case that must fail must fail for its stated reason and
+# must print no publish= decision.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+SCRIPT="$ROOT/scripts/research/research-v1-release-state.sh"
+command -v jq >/dev/null || { echo "FAIL: jq required" >&2; exit 1; }
+
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1
+git_q() { git -c user.name=t -c user.email=t@example.invalid -c init.defaultBranch=main "$@" >/dev/null; }
+
+# Remote: the pinned commit carries annotated research-v1; a later commit is main.
+git_q init -q "$work/origin"
+echo one >"$work/origin/f"; git_q -C "$work/origin" add f; git_q -C "$work/origin" commit -q -m one
+pinned="$(git -C "$work/origin" rev-parse HEAD)"
+git_q -C "$work/origin" tag -a research-v1 -m "research v1"
+echo two >"$work/origin/f"; git_q -C "$work/origin" commit -q -am two
+later="$(git -C "$work/origin" rev-parse HEAD)"
+# A remote without the tag.
+git_q clone -q --no-tags "$work/origin" "$work/notag"
+git_q -C "$work/notag" tag -d research-v1 2>/dev/null || true
+
+# Fixture release: four assets and a matching lock.
+good="$work/release.good"; mkdir -p "$good"
+printf '{"files": 668}\n' >"$good/archive-manifest.json"
+printf 'PK-payload-bytes' >"$good/bpfcompat-research-v1-payload.zip"
+sha() { sha256sum -- "$1" | awk '{print $1}'; }
+write_lock() { # <dir> -> lock in <dir>/archive-lock.json, checksums file
+  local d="$1"
+  jq -n --arg m "sha256:$(sha "$d/archive-manifest.json")" \
+    --arg p "sha256:$(sha "$d/bpfcompat-research-v1-payload.zip")" \
+    --argjson s "$(stat -c %s -- "$d/bpfcompat-research-v1-payload.zip")" \
+    '{schema_version: "bpfcompat.research.archive-lock.v1",
+      manifest: {sha256: $m}, payload_zip: {sha256: $p, size_bytes: $s}}' >"$d/archive-lock.json"
+  (cd "$d" && sha256sum archive-manifest.json archive-lock.json bpfcompat-research-v1-payload.zip >RELEASE-CHECKSUMS.txt)
+}
+write_lock "$good"
+cp "$good/archive-lock.json" "$work/repo-lock.json"
+
+# gh stub.
+#   STUB_RELEASE_DIR    assets served by `release view` (names) and `release download`
+#   STUB_VIEW           ok | notfound | error
+#   STUB_DRAFT / STUB_PRE   release flags (default false)
+#   STUB_DOWNLOAD_EXTRA     extra file dropped into the download dir
+#   STUB_ATTEST_FAIL        asset basename whose attestation fails
+mkdir -p "$work/bin"
+cat >"$work/bin/gh" <<'STUB'
+#!/usr/bin/env bash
+case "$1 $2" in
+  "release view")
+    case "${STUB_VIEW:-ok}" in
+      notfound) echo "release not found" >&2; exit 1 ;;
+      error) echo "HTTP 502: Bad Gateway" >&2; exit 1 ;;
+    esac
+    names="$(cd "$STUB_RELEASE_DIR" && find . -maxdepth 1 -type f -printf '%f\n' | jq -Rsc 'split("\n") | map(select(length>0)) | map({name: .})')"
+    jq -n --argjson a "$names" --argjson d "${STUB_DRAFT:-false}" --argjson p "${STUB_PRE:-false}" \
+      '{tagName: "research-v1", isDraft: $d, isPrerelease: $p, assets: $a}' ;;
+  "release download")
+    dir=""
+    while [[ $# -gt 0 ]]; do [[ "$1" == --dir ]] && dir="$2"; shift; done
+    cp "$STUB_RELEASE_DIR"/* "$dir/"
+    [[ -z "${STUB_DOWNLOAD_EXTRA:-}" ]] || printf x >"$dir/$STUB_DOWNLOAD_EXTRA" ;;
+  "attestation verify")
+    printf '%s\n' "$*" >>"$STUB_ATTEST_LOG"
+    [[ -n "${STUB_ATTEST_FAIL:-}" && "$(basename "$3")" == "$STUB_ATTEST_FAIL" ]] && exit 1
+    exit 0 ;;
+  *) echo "unexpected gh call: $*" >&2; exit 99 ;;
+esac
+STUB
+chmod +x "$work/bin/gh"
+export PATH="$work/bin:$PATH" STUB_ATTEST_LOG="$work/attest.log"
+
+rel="$work/release"
+reset_release() { rm -rf "$rel"; cp -a "$good" "$rel"; }
+
+fail=0
+# run <expect: false|true|fail> <description> <reason> [env assignments...]
+run() {
+  local expect="$1" desc="$2" reason="$3"; shift 3
+  : >"$STUB_ATTEST_LOG"
+  set +e
+  env STUB_RELEASE_DIR="$rel" BPFCOMPAT_RESEARCH_REMOTE="$work/origin" GITHUB_SHA="$later" "$@" \
+    bash "$SCRIPT" Kernel-Guard/bpfcompat research-v1 "$pinned" "$work/repo-lock.json" "$work/state" \
+    >"$work/out" 2>"$work/err"
+  local rc=$?
+  set -e
+  local ok=1
+  if [[ "$expect" == fail ]]; then
+    [[ "$rc" -ne 0 ]] || ok=0
+    grep -q 'publish=' "$work/out" && ok=0
+    grep -Fq -- "$reason" "$work/err" || ok=0
+  else
+    [[ "$rc" -eq 0 && "$(cat "$work/out")" == "publish=$expect" ]] || ok=0
+    [[ -z "$reason" ]] || grep -Fq -- "$reason" "$work/err" || ok=0
+  fi
+  if (( ok )); then
+    printf 'ok:   %s\n' "$desc"
+  else
+    printf 'FAIL: %s (rc=%s, expected %s / %s)\n' "$desc" "$rc" "$expect" "$reason" >&2
+    sed 's/^/      out: /' "$work/out" >&2; sed 's/^/      err: /' "$work/err" >&2
+    fail=1
+  fi
+}
+
+reset_release
+run false "intact release, later commit: verified, not re-published" "verified intact"
+[[ "$(wc -l <"$STUB_ATTEST_LOG")" -eq 4 ]] && grep -c -- "--source-digest $pinned --source-ref refs/heads/main" "$STUB_ATTEST_LOG" | grep -qx 4 &&
+  grep -c -- "--signer-workflow Kernel-Guard/bpfcompat/.github/workflows/scholarly-release-v1.yml" "$STUB_ATTEST_LOG" | grep -qx 4 &&
+  echo "ok:   all four assets attestation-verified against the pinned commit" ||
+  { echo "FAIL: attestation calls not bound to the pinned commit" >&2; cat "$STUB_ATTEST_LOG" >&2; fail=1; }
+
+run true "nothing published, running from the pinned commit: first publication" "first publication" \
+  BPFCOMPAT_RESEARCH_REMOTE="$work/notag" STUB_VIEW=notfound GITHUB_SHA="$pinned"
+run fail "nothing published, running from a later commit: never re-created" "would create a different research-v1" \
+  BPFCOMPAT_RESEARCH_REMOTE="$work/notag" STUB_VIEW=notfound
+run fail "tag without release" "tag exists without its release" STUB_VIEW=notfound
+run fail "release without tag" "release exists without its tag" BPFCOMPAT_RESEARCH_REMOTE="$work/notag"
+run fail "release lookup error is not 'absent'" "could not query release" STUB_VIEW=error
+run fail "unreachable tag remote" "could not query tag" BPFCOMPAT_RESEARCH_REMOTE="$work/does-not-exist"
+run fail "malformed GITHUB_SHA" "GITHUB_SHA is not a full SHA" GITHUB_SHA=main
+run fail "draft release" "is not the published four-asset research release" STUB_DRAFT=true
+run fail "prerelease" "is not the published four-asset research release" STUB_PRE=true
+
+# Tag moved / recreated elsewhere.
+git_q clone -q "$work/origin" "$work/moved"
+git_q -C "$work/moved" tag -d research-v1
+git_q -C "$work/moved" tag -a research-v1 -m moved "$later"
+run fail "tag peels to a different commit" "peels to $later" BPFCOMPAT_RESEARCH_REMOTE="$work/moved"
+git_q clone -q "$work/origin" "$work/light"
+git_q -C "$work/light" tag -d research-v1
+git_q -C "$work/light" tag research-v1 "$pinned"
+run fail "lightweight tag" "is not an annotated tag" BPFCOMPAT_RESEARCH_REMOTE="$work/light"
+
+reset_release; printf x >"$rel/extra.txt"
+run fail "extra release asset" "is not the published four-asset research release"
+reset_release; rm "$rel/archive-manifest.json"
+run fail "missing release asset" "is not the published four-asset research release"
+reset_release
+run fail "download returns an unlisted file" "do not match the expected four files" STUB_DOWNLOAD_EXTRA=injected.sh
+
+reset_release; printf ' ' >>"$rel/archive-lock.json"
+(cd "$rel" && sha256sum archive-manifest.json archive-lock.json bpfcompat-research-v1-payload.zip >RELEASE-CHECKSUMS.txt)
+run fail "published lock differs from the reviewed lock" "differs from the reviewed"
+
+# Payload swapped and every self-consistent file regenerated: only the
+# reviewed lock in the repository can catch it.
+reset_release; printf 'PK-evil' >"$rel/bpfcompat-research-v1-payload.zip"; write_lock "$rel"
+run fail "payload swapped with a regenerated lock" "differs from the reviewed"
+# Payload swapped while the lock is kept: lock binding catches it.
+reset_release; printf 'PK-evil' >"$rel/bpfcompat-research-v1-payload.zip"
+(cd "$rel" && sha256sum archive-manifest.json archive-lock.json bpfcompat-research-v1-payload.zip >RELEASE-CHECKSUMS.txt)
+run fail "payload swapped, lock kept" "does not match the archive lock"
+# Same-size swap: only the payload digest binding can catch it.
+reset_release; printf 'PK-payload-BYTES' >"$rel/bpfcompat-research-v1-payload.zip"
+(cd "$rel" && sha256sum archive-manifest.json archive-lock.json bpfcompat-research-v1-payload.zip >RELEASE-CHECKSUMS.txt)
+run fail "same-size payload swapped, lock kept" "does not match the archive lock"
+reset_release; printf '{"files": 669}\n' >"$rel/archive-manifest.json"
+(cd "$rel" && sha256sum archive-manifest.json archive-lock.json bpfcompat-research-v1-payload.zip >RELEASE-CHECKSUMS.txt)
+run fail "manifest swapped, lock kept" "does not match the archive lock"
+
+reset_release; sed -i '/payload.zip/d' "$rel/RELEASE-CHECKSUMS.txt"
+run fail "checksums file omits an asset" "does not list exactly the three archive files"
+reset_release; printf '%064d  archive-lock.json\n' 0 >>"$rel/RELEASE-CHECKSUMS.txt"
+run fail "checksums file lists an asset twice" "does not list exactly the three archive files"
+reset_release; sed -i '1s/  archive-manifest.json$/ *archive-manifest.json/' "$rel/RELEASE-CHECKSUMS.txt"
+run fail "checksums file uses a binary-mode marker" "does not list exactly the three archive files"
+reset_release; sed -i '1s/  archive-manifest.json$/  .\/archive-manifest.json/' "$rel/RELEASE-CHECKSUMS.txt"
+run fail "checksums file uses a relative path" "does not list exactly the three archive files"
+reset_release; sed -i "1s/^[0-9a-f]\{8\}/00000000/" "$rel/RELEASE-CHECKSUMS.txt"
+run fail "checksums file entry does not verify" "does not verify"
+
+reset_release
+for asset in archive-lock.json archive-manifest.json bpfcompat-research-v1-payload.zip RELEASE-CHECKSUMS.txt; do
+  run fail "missing attestation: $asset" "$asset has no scholarly-release-v1.yml attestation" STUB_ATTEST_FAIL="$asset"
+done
+
+if (( fail )); then
+  echo "test-release-state-v1: FAILED" >&2
+  exit 1
+fi
+echo "test-release-state-v1: all checks passed"

From acff42c630e0b100d5378a60e9beb24e829aa914 Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Wed, 14 Oct 2026 21:21:58 +0300
Subject: [PATCH 3/4] ci: keep the research-v1 state guard out of the frozen
 archive

research/archive/v1/archive-plan.json includes all of scripts/research/
in the immutable research-v1 payload. Adding the state guard and its test
there grew the rebuilt archive from 668 to 670 files. The pinned
archive-lock.json then no longer matched, and "Build and verify archival
payload" (research-archive-v1.yml) failed on 1daeb15, as it should.

Move them to scripts/research-v1-release-state.sh and
scripts/research-v1-release-state_test.sh and update every reference:
the scholarly workflow, ci.yml, check-release-consistency.sh and the
docs. A local rebuild from the pinned source artifacts again yields the
committed lock exactly: 668 files, manifest 6ed6d38d, payload 143a8e8a.
test-archive-v1.sh passes.

Signed-off-by: ErenAri <erenari27@gmail.com>
---
 .github/workflows/ci.yml                               |  2 +-
 .github/workflows/scholarly-release-v1.yml             |  4 ++--
 docs/workflow-token-permissions.md                     |  2 +-
 scripts/check-release-consistency.sh                   |  2 +-
 scripts/{research => }/research-v1-release-state.sh    |  3 +++
 ...e-state-v1.sh => research-v1-release-state_test.sh} | 10 +++++-----
 6 files changed, 13 insertions(+), 10 deletions(-)
 rename scripts/{research => }/research-v1-release-state.sh (97%)
 rename scripts/{research/test-release-state-v1.sh => research-v1-release-state_test.sh} (97%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index d6d152a9..39ac8980 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -134,7 +134,7 @@ jobs:
       - name: Research v1 release-state regression
         # scholarly-release-v1 re-runs on edits to itself; the immutable,
         # already-published research-v1 must be verified, never re-attempted.
-        run: bash scripts/research/test-release-state-v1.sh
+        run: bash scripts/research-v1-release-state_test.sh
       - name: Coverage-floor regression
         run: bash scripts/check-coverage_test.sh
       - name: Release metadata consistency
diff --git a/.github/workflows/scholarly-release-v1.yml b/.github/workflows/scholarly-release-v1.yml
index 956996b3..cee9651e 100644
--- a/.github/workflows/scholarly-release-v1.yml
+++ b/.github/workflows/scholarly-release-v1.yml
@@ -26,7 +26,7 @@ jobs:
   # job first establishes the publication state; the write-scoped publish job
   # runs only for the original first publication. An intact, verified
   # research-v1 ends the run green without a write token; a missing, partial
-  # or mismatched one fails here (scripts/research/research-v1-release-state.sh).
+  # or mismatched one fails here (scripts/research-v1-release-state.sh).
   state:
     name: Verify research v1 publication state
     runs-on: ubuntu-24.04
@@ -47,7 +47,7 @@ jobs:
           GH_TOKEN: ${{ github.token }}
         run: |
           set -euo pipefail
-          bash scripts/research/research-v1-release-state.sh \
+          bash scripts/research-v1-release-state.sh \
             "${GITHUB_REPOSITORY}" "${RESEARCH_TAG}" "${RESEARCH_COMMIT}" \
             research/archive/v1/archive-lock.json "${RUNNER_TEMP}/research-v1-state" \
             >>"$GITHUB_OUTPUT"
diff --git a/docs/workflow-token-permissions.md b/docs/workflow-token-permissions.md
index a4aca131..836cf2e0 100644
--- a/docs/workflow-token-permissions.md
+++ b/docs/workflow-token-permissions.md
@@ -59,7 +59,7 @@ belongs after graduation.
 `scholarly-release-v1.yml` runs on every push that changes its own file.
 `research-v1` was published once, from `141c491`, and is immutable.
 
-A read-only `state` job (`scripts/research/research-v1-release-state.sh`)
+A read-only `state` job (`scripts/research-v1-release-state.sh`)
 decides whether the write-scoped `publish` job may run:
 - **publish** only for the original first publication from the pinned commit;
 - **skip, green** only when the published tag, release, assets, lock,
diff --git a/scripts/check-release-consistency.sh b/scripts/check-release-consistency.sh
index 8f570378..392e8b31 100755
--- a/scripts/check-release-consistency.sh
+++ b/scripts/check-release-consistency.sh
@@ -127,7 +127,7 @@ for required_control in \
   '--verify-tag' \
   '--latest=false' \
   'RESEARCH_COMMIT: 141c491bd1508600338e7bc27abbc5a117eb7508' \
-  'bash scripts/research/research-v1-release-state.sh' \
+  'bash scripts/research-v1-release-state.sh' \
   'needs: state' \
   "if: needs.state.outputs.publish == 'true'"; do
   grep -Fq -- "$required_control" "$scholarly_workflow" ||
diff --git a/scripts/research/research-v1-release-state.sh b/scripts/research-v1-release-state.sh
similarity index 97%
rename from scripts/research/research-v1-release-state.sh
rename to scripts/research-v1-release-state.sh
index 89aac9a1..878e49d7 100755
--- a/scripts/research/research-v1-release-state.sh
+++ b/scripts/research-v1-release-state.sh
@@ -3,6 +3,9 @@
 #
 #   research-v1-release-state.sh <repository> <tag> <pinned-commit> <archive-lock.json> <work-dir>
 #
+# Lives outside scripts/research/ on purpose: that directory is part of the
+# frozen research-v1 archive payload (research/archive/v1/archive-plan.json).
+#
 # research-v1 is a one-time, immutable research release, created from
 # <pinned-commit>. The workflow re-runs whenever its own file changes on main,
 # so it must never re-attempt that publication from a later commit. Prints
diff --git a/scripts/research/test-release-state-v1.sh b/scripts/research-v1-release-state_test.sh
similarity index 97%
rename from scripts/research/test-release-state-v1.sh
rename to scripts/research-v1-release-state_test.sh
index 202983d9..f4113168 100755
--- a/scripts/research/test-release-state-v1.sh
+++ b/scripts/research-v1-release-state_test.sh
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Regression suite for scripts/research/research-v1-release-state.sh.
+# Regression suite for scripts/research-v1-release-state.sh.
 #
 # Real git (a local remote with a real annotated research-v1 tag); `gh` is a
 # stub serving a fixture release and logging attestation calls. Each case
@@ -7,8 +7,8 @@
 # must print no publish= decision.
 set -euo pipefail
 
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
-SCRIPT="$ROOT/scripts/research/research-v1-release-state.sh"
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT="$ROOT/scripts/research-v1-release-state.sh"
 command -v jq >/dev/null || { echo "FAIL: jq required" >&2; exit 1; }
 
 work="$(mktemp -d)"
@@ -182,7 +182,7 @@ for asset in archive-lock.json archive-manifest.json bpfcompat-research-v1-paylo
 done
 
 if (( fail )); then
-  echo "test-release-state-v1: FAILED" >&2
+  echo "research-v1-release-state_test: FAILED" >&2
   exit 1
 fi
-echo "test-release-state-v1: all checks passed"
+echo "research-v1-release-state_test: all checks passed"

From 1c6926b2651bc21551658fa17c13b939a7d1da6b Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Wed, 14 Oct 2026 21:26:04 +0300
Subject: [PATCH 4/4] docs: state exactly which Scorecard warnings become
 alerts

pkg/scorecard/sarif.go (shouldAddLocation) emits a warning as a SARIF
result only when the check is below the policy minimum, details are
enabled, and the warning has a file location; an inconclusive check is
skipped too. Found by independent review of #197.

Signed-off-by: ErenAri <erenari27@gmail.com>
---
 docs/workflow-token-permissions.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/workflow-token-permissions.md b/docs/workflow-token-permissions.md
index 836cf2e0..e037407a 100644
--- a/docs/workflow-token-permissions.md
+++ b/docs/workflow-token-permissions.md
@@ -22,8 +22,10 @@ two levels differently:
   permissions.
 
 The SARIF output that becomes code-scanning alerts (`pkg/scorecard/sarif.go`)
-skips a check whose score meets the policy minimum. Below it, every warning
-becomes an alert carrying the check score. That is why one top-level grant in
+skips a check whose score meets the policy minimum, or is inconclusive.
+Below the minimum, with details enabled, each warning that has a file location
+becomes an alert carrying the check score (`shouldAddLocation`). That is why
+one top-level grant in
 `scholarly-release-v1.yml` (alert #178) also turned the five required
 job-level grants into "score is 0" alerts (#173–#177).