fix(bootstrap): R5 reviewer findings + log4j-api umbrella CPE bump (RAN-47)

Reviewer round-5 found 3 blockers on `6e7e911` (RAN-47 cf64b44d) plus the
CI build remained red on a single log4j-api umbrella-CPE attribution.

R5-1 — release-java.yml `git commit -S` non-interactive GPG.
  setup-java only wires MAVEN_GPG_PASSPHRASE into Maven's settings.xml;
  git itself has no equivalent autoconfig and `git commit -S` invokes
  gpg interactively by default, which fails in Actions for passphrase-
  protected keys. Configured a non-interactive gpg-agent (gpg.conf with
  pinentry-mode loopback, gpg-agent.conf with allow-loopback-pinentry)
  and wired git.gpg.program to a thin wrapper that exec's into
  `gpg --batch --yes --pinentry-mode loopback --passphrase "$MAVEN_GPG_PASSPHRASE"`.
  MAVEN_GPG_PASSPHRASE is already passed on each step that signs.

R5-2 — scripts/setup-git-signed.sh OpenPGP key-id support.
  Previous version forced an SSH-style file-existence check on
  user.signingkey, rejecting contributors whose global config uses
  gpg.format=openpgp with a key id / fingerprint. Added GIT_GPG_FORMAT
  resolution (env > global > "ssh" default) and per-format validation:
    - ssh:     existing path-on-disk check
    - openpgp: gpg --list-secret-keys must know the key
    - x509:    gpgsm --list-secret-keys must know the key
    - other:   reject with a clear error
  Maintainer's defaults are unchanged (still ssh-format).

R5-3 — first-time-setup.md fast-loop scope clarified.
  `mvn test` only runs Surefire (unit tests); this repo's integration
  tests are wired through Failsafe at `integration-test`/`verify`.
  Added a fourth `mvn verify -Dspotbugs.skip ...` form for unit +
  integration in the inner loop, plus a clarifying paragraph.

CI fix — log4j-api 2.25.3 → 2.25.4.
  CI on `6e7e911` was failing solely on:
    log4j-api-2.25.3.jar : CVE-2026-34478, CVE-2026-34480, CVE-2026-34481
  These are log4j-core CVEs attributed to log4j-api by the umbrella
  cpe:2.3:a:apache:log4j:* CPE match. log4j-core 2.25.4 was already
  pinned in dependencyManagement; mirrored the pin to log4j-api so
  the umbrella-CPE attribution clears (the API jar contains no
  vulnerable code; this is a clean trail-consistency bump, not a
  suppression). Comment on the override block updated to reflect.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: 3 people

.github/workflows/release-java.yml

@@ -23,7 +23,7 @@ jobs:
           server-password: MAVEN_PASSWORD
           gpg-private-key: ${{ secrets.MAVEN_GPG_PRIVATE_KEY }}
           gpg-passphrase: MAVEN_GPG_PASSPHRASE
-      - name: Configure git identity for signed release commit and tag
+      - name: Configure git identity and non-interactive GPG for signed commit/tag
         run: |
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git config user.name  "github-actions[bot]"
@@ -38,9 +38,36 @@ jobs:
           git config gpg.format       openpgp
           git config commit.gpgsign   true
           git config tag.gpgsign      true
+          # Reviewer finding cf64b44d (RAN-47, R5-1):
+          # `git commit -S` / `git tag -s` invoke gpg interactively by default
+          # and fail in non-interactive Actions shells when the imported key
+          # has a passphrase. setup-java only wires the passphrase for Maven
+          # signing (via MAVEN_GPG_PASSPHRASE in settings.xml); git itself
+          # has no equivalent autoconfig. Configure the gpg-agent for loopback
+          # pinentry, point gpg.program at a thin wrapper that injects
+          # --batch / --pinentry-mode loopback / --passphrase from
+          # MAVEN_GPG_PASSPHRASE, so signing succeeds non-interactively.
+          mkdir -p "$HOME/.gnupg"
+          chmod 700 "$HOME/.gnupg"
+          printf '%s\n' 'use-agent' 'pinentry-mode loopback' > "$HOME/.gnupg/gpg.conf"
+          printf '%s\n' 'allow-loopback-pinentry' > "$HOME/.gnupg/gpg-agent.conf"
+          gpgconf --kill gpg-agent || true
+          # Wrapper script: git invokes this with the same flags as gpg.
+          # We exec into gpg with --batch + loopback + the passphrase from
+          # the env (MAVEN_GPG_PASSPHRASE is set on each step that signs).
+          cat > "$HOME/.gnupg/gpg-loopback.sh" <<'WRAPPER'
+          #!/usr/bin/env bash
+          # Non-interactive gpg wrapper for `git commit -S` / `git tag -s`.
+          # MAVEN_GPG_PASSPHRASE is set on the workflow step that signs.
+          exec gpg --batch --yes --pinentry-mode loopback \
+            --passphrase "${MAVEN_GPG_PASSPHRASE:-}" "$@"
+          WRAPPER
+          chmod +x "$HOME/.gnupg/gpg-loopback.sh"
+          git config gpg.program "$HOME/.gnupg/gpg-loopback.sh"
       - name: Set release version and create signed release commit
         env:
           RELEASE_VERSION: ${{ inputs.version }}
+          # Picked up by the gpg-loopback wrapper script for `git commit -S`.
           MAVEN_GPG_PASSPHRASE: ${{ secrets.MAVEN_GPG_PASSPHRASE }}
         # Commit the version bump on a detached HEAD off the workflow's
         # checkout. The commit is reachable only via the tag created below —

pom.xml

@@ -62,8 +62,14 @@
                 log4j-core 2.25.3 -> 2.25.4          (CVE-2026-34477 MOD,
                                                       CVE-2026-34478 MOD,
                                                       CVE-2026-34480 MOD)
+                log4j-api 2.25.3 -> 2.25.4           (umbrella-CPE attribution
+                                                      of log4j-core CVEs;
+                                                      bumped to keep the dep
+                                                      tree consistent and to
+                                                      stop the dep-check
+                                                      umbrella match)
                 log4j-layout-template-json 2.25.3 -> 2.25.4  (CVE-2026-34481 MOD)
-                  •both pulled in transitively by Neo4j 2026.02.3.
+                  •all three pulled in transitively by Neo4j 2026.02.3.
                 shiro-core 2.0.6 -> 2.1.0            (CVE-2026-23901 LOW)
                   •pulled in by neo4j-security.
                 mcp-core 1.1.0 -> 1.1.1              (CVE-2026-34237 MOD)
@@ -77,6 +83,11 @@
                 <artifactId>log4j-core</artifactId>
                 <version>2.25.4</version>
             </dependency>
+            <dependency>
+                <groupId>org.apache.logging.log4j</groupId>
+                <artifactId>log4j-api</artifactId>
+                <version>2.25.4</version>
+            </dependency>
             <dependency>
                 <groupId>org.apache.logging.log4j</groupId>
                 <artifactId>log4j-layout-template-json</artifactId>

scripts/setup-git-signed.sh

@@ -1,14 +1,21 @@
 #!/usr/bin/env bash
 # scripts/setup-git-signed.sh
 #
-# Apply the repo-local git config required by RAN-46 AC #2.
+# Apply the repo-local git config required by RAN-46 AC #2. Supports BOTH
+# ssh-format and openpgp-format signing — picks up whichever the contributor
+# already has wired into their global git config.
 #
-#   user.name        = Amit Kumar
-#   user.email       = ak.nitrr13@gmail.com
+# Defaults (when nothing is set globally):
 #   user.signingkey  = ~/.ssh/id_ed25519.pub
 #   gpg.format       = ssh
-#   commit.gpgsign   = true
-#   tag.gpgsign      = true
+#
+# Honored env / global-config inputs:
+#   GIT_USER_NAME       (else: git config --global user.name)
+#   GIT_USER_EMAIL      (else: git config --global user.email)
+#   GIT_SIGNING_KEY     (else: git config --global user.signingkey,
+#                              else default SSH key)
+#   GIT_GPG_FORMAT      (else: git config --global gpg.format,
+#                              else "ssh")
 #
 # Idempotent: re-running is a no-op except for the verification block at the end.
 # Run from the repo root (or any subdirectory of the worktree).
@@ -26,10 +33,11 @@ cd "$repo_root"
 # Identity is taken from env vars first, then from the user's GLOBAL git
 # config — never hard-coded to the maintainer. This avoids silently
 # misattributing every contributor's signed commits to the maintainer
-# (Reviewer finding #3).
+# (earlier Reviewer finding).
 GIT_USER_NAME=${GIT_USER_NAME:-$(git config --global --get user.name 2>/dev/null || true)}
 GIT_USER_EMAIL=${GIT_USER_EMAIL:-$(git config --global --get user.email 2>/dev/null || true)}
 GIT_SIGNING_KEY=${GIT_SIGNING_KEY:-$(git config --global --get user.signingkey 2>/dev/null || echo "$HOME/.ssh/id_ed25519.pub")}
+GIT_GPG_FORMAT=${GIT_GPG_FORMAT:-$(git config --global --get gpg.format 2>/dev/null || echo "ssh")}
 
 if [ -z "$GIT_USER_NAME" ] || [ -z "$GIT_USER_EMAIL" ]; then
   cat >&2 <<'EOF'
@@ -48,10 +56,17 @@ EOF
   exit 4
 fi
 
-# The signing key path must exist before we wire up signing — otherwise every
-# commit will fail and the local config will be silently broken.
-if [ ! -f "$GIT_SIGNING_KEY" ]; then
-  cat >&2 <<EOF
+# Signing-key validation depends on gpg.format:
+#   - ssh:     user.signingkey is a path on disk (the file must exist)
+#   - openpgp: user.signingkey is a key id / fingerprint (gpg must know it)
+#   - x509:    user.signingkey is a key id / fingerprint (gpgsm must know it)
+# Reviewer finding cf64b44d (RAN-47, R5-2): the previous version forced the
+# ssh-path check unconditionally, which rejected contributors using OpenPGP
+# globally even when their key chain was healthy.
+case "$GIT_GPG_FORMAT" in
+  ssh)
+    if [ ! -f "$GIT_SIGNING_KEY" ]; then
+      cat >&2 <<EOF
 error: SSH signing key not found at $GIT_SIGNING_KEY
 
 Generate one with:
@@ -60,8 +75,39 @@ Then upload the public key (\$GIT_SIGNING_KEY) to your GitHub account under:
     Settings → SSH and GPG keys → New SSH key → Key type: Signing Key
 And re-run this script.
 EOF
-  exit 2
-fi
+      exit 2
+    fi
+    ;;
+  openpgp|gpg)
+    if ! gpg --list-secret-keys --with-colons "$GIT_SIGNING_KEY" 2>/dev/null | grep -q '^sec:'; then
+      cat >&2 <<EOF
+error: OpenPGP signing key '$GIT_SIGNING_KEY' not found in your gpg keyring.
+
+Either point user.signingkey at a key id / fingerprint that
+\`gpg --list-secret-keys\` knows, or generate / import a key first:
+    gpg --full-generate-key
+    git config --global user.signingkey <KEY_ID>
+And re-run this script.
+EOF
+      exit 2
+    fi
+    ;;
+  x509)
+    if ! gpgsm --list-secret-keys "$GIT_SIGNING_KEY" >/dev/null 2>&1; then
+      cat >&2 <<EOF
+error: x509 signing key '$GIT_SIGNING_KEY' not found via gpgsm.
+
+Configure x509 signing keys in gpgsm and ensure
+\`gpgsm --list-secret-keys\` reports your key, then re-run.
+EOF
+      exit 2
+    fi
+    ;;
+  *)
+    echo "error: unsupported gpg.format '$GIT_GPG_FORMAT' (expected ssh, openpgp, gpg, or x509)." >&2
+    exit 5
+    ;;
+esac
 
 apply() {
   local key="$1" value="$2"
@@ -71,7 +117,7 @@ apply() {
 apply user.name        "$GIT_USER_NAME"
 apply user.email       "$GIT_USER_EMAIL"
 apply user.signingkey  "$GIT_SIGNING_KEY"
-apply gpg.format       ssh
+apply gpg.format       "$GIT_GPG_FORMAT"
 apply commit.gpgsign   true
 apply tag.gpgsign      true
 

shared/runbooks/first-time-setup.md

@@ -89,12 +89,14 @@ For a faster inner loop while iterating:
 
 ```bash
 mvn -B -ntp test \
-  -Dspotbugs.skip=true -Ddependency-check.skip=true     # unit + integration, no static analysis / CVE plugins
-mvn -B -ntp -Dtest=SomeDetectorTest test                # single test class
+  -Dspotbugs.skip=true -Ddependency-check.skip=true     # unit tests only (Surefire), no static analysis / CVE plugins
+mvn -B -ntp -Dtest=SomeDetectorTest test                # single unit test class
 mvn -B -ntp -DskipTests=true package                    # JAR only, no tests
+mvn -B -ntp verify \
+  -Dspotbugs.skip=true -Ddependency-check.skip=true     # unit + integration tests (Surefire + Failsafe), no static analysis / CVE plugins
 ```
 
-The first command **does run tests** — earlier drafts incorrectly passed `-DskipTests` here, which would have skipped them. Use `-Dspotbugs.skip` / `-Ddependency-check.skip` to keep the inner loop fast without dropping test coverage.
+The first command **does run tests** — earlier drafts incorrectly passed `-DskipTests` here, which would have skipped them. Reviewer finding cf64b44d (RAN-47, R5-3): Maven's `test` phase only runs Surefire (unit tests). This repo's integration tests are wired through Failsafe at the `integration-test` / `verify` phases — use the fourth form above when you need both unit + integration in the inner loop. Use `-Dspotbugs.skip` / `-Ddependency-check.skip` to keep things fast without dropping test coverage.
 
 Smoke-test the CLI end-to-end against this repo: