From 405822e99fd4f50d6b0739abe5040cef2ef63f7b Mon Sep 17 00:00:00 2001
From: Manfred Riem <15701806+mnriem@users.noreply.github.com>
Date: Mon, 5 Oct 2026 14:10:35 -0500
Subject: [PATCH] ci: add advanced CodeQL scanning

Retain Actions and JavaScript/TypeScript analysis with weekly coverage and fork-eligible pull request scanning. Document the separately coordinated default-to-advanced activation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .github/workflows/codeql.yml | 36 ++++++++++++++++++++++++++++++++++++
 AGENTS.md                    | 25 +++++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 .github/workflows/codeql.yml

diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 00000000..60d6bd45
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,36 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '23 4 * * 2'
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ['actions', 'javascript-typescript']
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
+        with:
+          category: /language:${{ matrix.language }}
diff --git a/AGENTS.md b/AGENTS.md
index 1af06ef4..2e98e43e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -157,6 +157,31 @@ symlinks in the package root or contents before reading manifests or creating
 archives; shell `zip` follows links and must never archive files outside the
 package.
 
+## Advanced CodeQL scanning
+
+`.github/workflows/codeql.yml` follows Spec Kit's advanced workflow, retaining
+this repository's `actions` and `javascript-typescript` languages and default
+query suite. It scans pushes and pull requests targeting `main`, without path
+filters or fork exclusions. Use `pull_request`, never `pull_request_target` with
+untrusted code; GitHub's fork-contributor workflow approval policies still apply.
+The Tuesday 04:23 UTC schedule deliberately preserves default setup's weekly
+coverage, beyond Spec Kit's unscheduled workflow. Keep actions SHA-pinned and
+the analysis job limited to `contents: read` and `security-events: write`.
+No dependency installation or build step is needed for these languages.
+
+Activation requires a coordinated maintainer switch, not just a YAML change:
+
+1. Review and merge the replacement workflow while default setup remains enabled.
+   Default setup rejects advanced CodeQL SARIF uploads while both are present.
+2. Once the approved workflow is on `main`, an authorized maintainer must disable
+   default setup in the target repository's code-scanning settings and re-run the
+   merge-triggered CodeQL workflow. Do not disable default setup prematurely.
+3. Verify successful uploads for both `/language:actions` and
+   `/language:javascript-typescript` on `main` and an approved fork PR run.
+   Local YAML checks are not evidence of a live scan. Required checks, rulesets,
+   fork Actions settings, and other security settings are separate maintainer
+   decisions; do not change them as part of this switch.
+
 ## When revving the core skills plugin
 
 1. Re-enumerate the `specify` CLI surface for the **latest** release