feat(workflows): add reusable dependency-review.yml for 4 product repos

.github/workflows/dependency-review.yml

@@ -0,0 +1,139 @@
+# Reusable Dependency Review (workflow_call), consolidating the four
+# near-identical dependency-review.yml files argos, mightyETL, newsdom-api,
+# and scopeweave each carried independently. See
+# docs/adr/0024-dependency-review-reusable-workflow-consolidation.md and
+# docs/doctoring/dependency-review-reusable-workflow-consolidation.md for the
+# per-repo field audit behind these inputs.
+#
+# The `on: pull_request` trigger (and any branch restriction) stays in each
+# calling repo's own thin workflow file -- a workflow_call target cannot also
+# be the thing GitHub triggers directly on pull_request.
+#
+# Dependency Review requires GitHub Dependency Graph (and, on private repos
+# without GitHub Advanced Security, it is unavailable regardless of a repo's
+# own settings). scopeweave's original workflow already detected this
+# dynamically via the dependency-graph compare API instead of assuming from
+# public/private repository status (mightyETL's original approach, which is
+# wrong for a private repo that does have GHAS). This reusable workflow
+# adopts the dynamic detection as the common, more-correct behavior for
+# every caller, so no per-repo public/private input is needed.
+#
+# Example caller (.github/workflows/dependency-review.yml in a product repo):
+#
+#   name: Dependency Review
+#   on:
+#     pull_request:
+#   concurrency:
+#     group: dependency-review-${{ github.event.pull_request.number || github.ref }}
+#     cancel-in-progress: true
+#   jobs:
+#     dependency-review:
+#       uses: ContextualWisdomLab/.github/.github/workflows/dependency-review.yml@main
+#       with:
+#         fail_on_severity: high
+#         allow_ghsas: "GHSA-69w3-r845-3855"
+
+name: Reusable Dependency Review
+
+on:
+  workflow_call:
+    inputs:
+      fail_on_severity:
+        description: "Value forwarded to dependency-review-action's fail-on-severity input."
+        required: false
+        type: string
+        default: "moderate"
+      allow_ghsas:
+        description: >-
+          Comma-or-newline-separated GHSA IDs forwarded to
+          dependency-review-action's allow-ghsas input. Empty (the default)
+          allows none.
+        required: false
+        type: string
+        default: ""
+      continue_on_error:
+        description: >-
+          Whether the dependency-review step itself is allowed to fail
+          without failing the job (argos's original behavior, which relies
+          on a separate blocking OSV-Scanner gate instead of this one).
+          Default false makes the dependency-review step itself blocking.
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    env:
+      # Opts every JS action this job runs (checkout, dependency-review-action)
+      # into the Node 24 actions runtime ahead of GitHub's default cutover,
+      # matching newsdom-api's original workflow -- applied uniformly here
+      # since it is a forward-compatibility setting, not a per-repo policy.
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+
+      - name: Check dependency graph availability
+        id: dependency_graph
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REPOSITORY: ${{ github.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          if [ "${{ github.event_name }}" != "pull_request" ]; then
+            echo "available=false" >>"$GITHUB_OUTPUT"
+            echo "Dependency review only runs as a hard gate for pull_request events."
+            exit 0
+          fi
+
+          api_url="${GITHUB_API_URL:-https://api.github.com}"
+          response_file="$(mktemp)"
+          status="$(
+            curl -fsS -o "$response_file" -w '%{http_code}' \
+              -H "Accept: application/vnd.github+json" \
+              -H "Authorization: Bearer ${GH_TOKEN}" \
+              -H "X-GitHub-Api-Version: 2022-11-28" \
+              "${api_url}/repos/${REPOSITORY}/dependency-graph/compare/${BASE_SHA}...${HEAD_SHA}" \
+              || true
+          )"
+
+          if [ "$status" = "200" ]; then
+            echo "available=true" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          if [ "$status" = "403" ] || [ "$status" = "404" ]; then
+            echo "::warning::Dependency graph compare returned HTTP ${status} for ${REPOSITORY}; skipping the dependency-review hard gate (GitHub Dependency Graph, or GitHub Advanced Security on a private repository, is unavailable)."
+            echo "available=false" >>"$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "::error::Dependency graph availability check failed with HTTP ${status}. This is not a 'graph unavailable' response (403/404) -- treating it as a genuine failure instead of silently skipping the security gate."
+          cat "$response_file"
+          exit 1
+
+      - name: Dependency review
+        if: steps.dependency_graph.outputs.available == 'true'
+        continue-on-error: ${{ inputs.continue_on_error }}
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
+        with:
+          fail-on-severity: ${{ inputs.fail_on_severity }}
+          allow-ghsas: ${{ inputs.allow_ghsas }}
+          comment-summary-in-pr: on-failure
+
+      - name: Dependency graph unavailable note
+        if: steps.dependency_graph.outputs.available != 'true' && github.event_name == 'pull_request'
+        run: |
+          echo "Dependency Review requires GitHub Dependency Graph to be enabled for this repository (and, on private repositories, GitHub Advanced Security)."
+          echo "Other required dependency-vulnerability gates (OSV-Scanner, Scorecard) remain the blocking coverage until Dependency Graph is available here."

docs/adr/0024-dependency-review-reusable-workflow-consolidation.md

@@ -0,0 +1,120 @@
+# ADR-0024: Consolidate per-repo Dependency Review workflows into one reusable workflow
+
+- **Status:** Accepted
+- **Date:** 2026-09-02
+- **Scope:** `.github/workflows/dependency-review.yml` (new, central, `workflow_call`);
+  thin callers in `argos`, `mightyETL`, `newsdom-api`, `scopeweave`
+
+## Context
+
+Four repositories each carried an independently hand-written
+`dependency-review.yml` running `actions/dependency-review-action` on pull
+requests: `argos`, `mightyETL`, `newsdom-api`, `scopeweave`. This is exactly
+the drift `docs/CWL-MASTER-CONTEXT.md` §7 and this repo's own
+"individual-repository workflow duplication" standardization effort target —
+per-repo copies of the same control drift independently and cost bootup time
+on every PR run.
+
+A field-by-field audit of all four files (2026-09-02) found:
+
+| Field | argos | mightyETL | newsdom-api | scopeweave |
+| --- | --- | --- | --- | --- |
+| `fail-on-severity` | `moderate` | `high` | unset (action default `low`) | `moderate` |
+| `allow-ghsas` | none | none | `GHSA-69w3-r845-3855` | none |
+| `comment-summary-in-pr` | unset | unset | unset | `on-failure` |
+| step-level `continue-on-error` | `true` | unset (blocking) | unset (blocking) | unset (blocking) |
+| Dependency Graph availability handling | none (always runs, no fallback) | static `github.event.repository.private` branch to a separate no-op job | none | dynamic API preflight (`dependency-graph/compare` HTTP status): 200 → run the gate, 403/404 → warn and skip, any other status → hard-fail the job |
+| trigger scope | `pull_request: branches: [main, developmental]` | `pull_request` (all branches) | `pull_request` (all branches) | `pull_request` + `workflow_dispatch` |
+| concurrency group | none | `${{ github.workflow }}-${{ github.event.pull_request.number \|\| github.ref }}` | none | `dependency-review-${{ github.event.pull_request.number \|\| github.ref }}` |
+| `actions/checkout` pin | unpinned `@v4` | n/a (action doesn't need checkout) | SHA `3d3c42e5...` | SHA `9c091bb2...` (v7.0.0) |
+| `dependency-review-action` pin | unpinned `@v4` | SHA `a1d282b3...` (v5.0.0) | SHA `a1d282b3...` | SHA `a1d282b3...` |
+| `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` | unset | unset | `true` | unset |
+
+Two findings changed the design from a naive copy-paste consolidation:
+
+1. **Severity and the GHSA allowlist genuinely vary per repo** — these are
+   real policy differences (newsdom-api carries a documented upstream false
+   positive it allowlists; mightyETL runs a stricter `high`-only gate), not
+   accidental drift. They must stay per-caller inputs, not get silently
+   flattened to one value.
+2. **mightyETL's public/private branch is the wrong generalization.**
+   `github.event.repository.private == false` assumes GHAS availability
+   tracks repository visibility, but a private repository can have GitHub
+   Advanced Security enabled (making Dependency Graph available) while a
+   public repository can still lack Dependency Graph in edge cases. scopeweave's
+   dynamic preflight — call the dependency-graph compare API directly and
+   check the HTTP status — checks the actual capability rather than inferring
+   it, and already existed independently in one of the four originals. This
+   ADR generalizes scopeweave's approach to all four callers rather than
+   mightyETL's, and drops the separate no-op fallback job in favor of one job
+   with a conditional step (the same job either runs the gate or emits the
+   unavailability note, never both, with no risk of the fallback job being
+   forgotten when Dependency Graph later becomes available). scopeweave's
+   preflight also distinguishes a confirmed-unavailable response (403/404 —
+   warn and skip) from any other unexpected HTTP status (500, an auth
+   failure, a transient GitHub API problem — hard-fail the job instead of
+   silently skipping the security gate); the reusable workflow preserves
+   that exact distinction rather than the simpler "any non-200 means
+   unavailable" behavior an initial draft of this workflow used, since
+   collapsing a real failure into "unavailable" would silently drop
+   coverage instead of surfacing the problem.
+3. **`comment-summary-in-pr: on-failure` is a uniformly-beneficial UX
+   improvement, not a policy choice.** Only scopeweave's original set it
+   (posts the dependency-review findings as a PR comment when the gate
+   fails). It changes nothing about pass/fail semantics, only where a
+   failure's detail is surfaced, so it is hardcoded uniformly rather than
+   made an input — the other three repositories gain it for free.
+4. **`FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` is a forward-compatibility setting,
+   not a policy choice.** newsdom-api was the only original to set it,
+   opting its job into GitHub's Node 24 actions runtime ahead of the default
+   cutover for the JS actions it runs (`actions/checkout`,
+   `actions/dependency-review-action` — both JS actions in every one of the
+   four originals). There is no reason the other three repositories should
+   not also get this ahead of Node 20's eventual end-of-life, so it is
+   hardcoded uniformly in the reusable workflow's job `env`, not made an
+   input.
+
+## Decision
+
+Add `.github/workflows/dependency-review.yml` to `ContextualWisdomLab/.github`
+as a `workflow_call` reusable workflow with three inputs for the
+genuinely-varying fields: `fail_on_severity` (string, default `"moderate"`),
+`allow_ghsas` (string, default `""`), and `continue_on_error` (boolean,
+default `false`, for argos's non-blocking original behavior). The dynamic
+Dependency Graph availability check (scopeweave's design) is hardcoded and
+uniform for every caller — it is a correctness fix, not a policy choice, so
+it does not need to be an input.
+
+Each of the four repositories keeps a thin caller workflow with its own
+`on: pull_request` trigger (including argos's `branches:` restriction, which
+cannot live inside a `workflow_call` target), a `concurrency` group (added to
+argos and newsdom-api, which lacked one, bringing all four to the same
+cancel-in-progress-on-repush posture used elsewhere in the org per the
+concurrency-standardization pass this workflow-consolidation effort is part
+of), and `with:` values reproducing that repository's original severity and
+allowlist exactly. The old hand-written workflow bodies are deleted from each
+repository in the same change, per this org's "repository-local copies are
+drift sources, not repo-specific contracts" principle
+(`README.md` policy summary; this repo's own `CLAUDE.md`).
+
+## Consequences
+
+- One place to fix a bug in the dependency-review logic (e.g. the
+  availability-detection curl call) instead of four.
+- Each repository keeps its own severity/allowlist policy explicitly and
+  visibly in its own thin caller, not hidden in a shared default that could
+  silently loosen or tighten a repo's actual gate.
+- argos and newsdom-api gain the cancel-in-progress concurrency group they
+  previously lacked, at no cost — a stale run for a superseded push no longer
+  keeps running or occupying a runner slot.
+- `mightyETL`'s previous two-job (public/private) shape becomes one job; the
+  private-repo fallback note now fires from a live capability check instead
+  of an assumption, so it no longer misclassifies a private+GHAS-enabled
+  repository as unsupported, or a public+Dependency-Graph-disabled repository
+  as supported.
+- argos's `unpinned @v4` and `newsdom-api`'s slightly older checkout pin are
+  both upgraded to the same current, verified pins the reusable workflow
+  uses, closing that drift too.
+
+See `docs/doctoring/dependency-review-reusable-workflow-consolidation.md` for
+the full per-repo audit and the exact diffs each caller received.