B7: CodeQL workflow + pre-commit config

.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: CodeQL
+
+# Static analysis for Python via GitHub's CodeQL. Runs on pushes to main,
+# PRs targeting main, and weekly so we still get fresh scans on dormant
+# weeks. Findings show up under the "Security" tab.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "23 6 * * 1"  # Mondays 06:23 UTC (off-peak, low contention)
+
+jobs:
+  analyze:
+    name: Analyze (python)
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+          queries: security-and-quality
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:python"

.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# Run automatically before each commit. Install once with:
+#   pip install pre-commit && pre-commit install
+#
+# Run manually across the whole repo with:
+#   pre-commit run --all-files
+#
+# These hooks mirror what CI enforces, so a clean local commit means a
+# green CI run (modulo the test suite, which pre-commit doesn't run).
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+      - id: detect-private-key
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

CHANGELOG.md

@@ -22,6 +22,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Issue and pull request templates under `.github/`.
 - Dependabot configuration for weekly dependency and Actions updates.
 - `.env.example` documenting the supported environment variables.
+- CodeQL workflow (`.github/workflows/codeql.yml`) running GitHub's
+  `security-and-quality` Python query suite on every push, PR, and
+  weekly. Findings surface under the repo's Security tab.
+- `pre-commit` config (`.pre-commit-config.yaml`) running ruff,
+  trailing-whitespace / EOF / YAML / TOML / merge-conflict / large-file
+  / private-key hooks before each commit. `CONTRIBUTING.md` updated
+  with install instructions.
 
 ### Security
 - `SUBSTACK_COOKIE` environment variable is now supported as a safer

CONTRIBUTING.md

@@ -10,14 +10,23 @@ cd substack-broken-link-checker
 python -m venv .venv
 source .venv/bin/activate  # Windows: .venv\Scripts\activate
 pip install -e ".[dev]"
+
+# Optional but recommended: install pre-commit hooks so the same lint
+# checks CI runs fire automatically before each commit.
+pip install pre-commit
+pre-commit install
 ```
 
 ## Before opening a PR
 
-- Run the linter: `ruff check .`
-- Run the formatter: `ruff format .`
-- Run the tests: `pytest`
-- Verify the CLI still launches: `python substack_link_checker.py --help`
+If you installed pre-commit (above), the lint/format checks run on every
+commit. Otherwise run them yourself:
+
+- `ruff check .` — lint
+- `ruff format .` — auto-format
+- `pre-commit run --all-files` — runs everything pre-commit would
+- `pytest` — test suite
+- `python substack_link_checker.py --help` — smoke-test the CLI
 
 ## Filing issues