Make uv sync reproducible on Python 3.12 and macOS

.github/workflows/skillgate.yml

@@ -16,15 +16,18 @@ jobs:
       security-events: write
     steps:
       - uses: actions/checkout@v7
-      - uses: actions/setup-python@v6
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
         with:
-          python-version: "3.11"
-      - name: Install SkillGate
-        run: python -m pip install -e ".[dev]"
+          version: "0.11.26"
+          python-version: "3.12"
+          enable-cache: true
+      - name: Sync development environment
+        run: uv sync --locked
       - name: Check golden snapshots
         id: snapshots
         continue-on-error: true
-        run: python tools/update_snapshots.py --check --artifacts test-outputs/snapshots
+        run: uv run python tools/update_snapshots.py --check --artifacts test-outputs/snapshots
       - name: Upload snapshot review artifacts
         if: steps.snapshots.outcome == 'failure'
         uses: actions/upload-artifact@v7
@@ -35,22 +38,42 @@ jobs:
         if: steps.snapshots.outcome == 'failure'
         run: exit 1
       - name: Run tests
-        run: python -m pytest
+        run: uv run python -m pytest
       - name: Run lint
-        run: python -m ruff check .
+        run: uv run ruff check .
       - name: Check formatting
-        run: python -m ruff format --check .
+        run: uv run ruff format --check .
       - name: Scan repository
-        run: skillgate scan . --format text
+        run: uv run skillgate scan . --format text
       - name: Run policy smoke check
-        run: skillgate check fixtures/benchmark/01-safe-documentation-skill --policy skillgate.example.yaml
+        run: uv run skillgate check fixtures/benchmark/01-safe-documentation-skill --policy skillgate.example.yaml
       - name: Verify benchmark fixtures
-        run: skillgate fixtures summary fixtures/benchmark --format text
+        run: uv run skillgate fixtures summary fixtures/benchmark --format text
       - name: Generate SARIF
         if: always()
-        run: skillgate scan . --format sarif --output skillgate.sarif
+        run: uv run skillgate scan . --format sarif --output skillgate.sarif
       - name: Upload SARIF
         if: always()
         uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: skillgate.sarif
+
+  macos-python312:
+    name: macOS ARM64 / Python 3.12
+    runs-on: macos-14
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          version: "0.11.26"
+          python-version: "3.12"
+          enable-cache: true
+      - name: Sync locked environment
+        run: uv sync --locked
+      - name: Verify tests on Apple Silicon
+        run: uv run python -m pytest

.python-version

@@ -0,0 +1 @@
+3.12

CONTRIBUTING.md

@@ -4,15 +4,32 @@ Thanks for helping improve SkillGate. The project is a deterministic static scan
 
 ## Development Setup
 
+The repository is pinned to Python 3.12 for local development through `.python-version`. The full test suite also requires Node.js because it validates the experimental Node wrapper.
+
+On an Apple Silicon Mac with Homebrew:
+
 ```bash
-python -m pip install -e ".[dev]"
-python -m pytest
-python tools/update_snapshots.py --check
-python -m ruff check .
-python -m ruff format --check .
+brew install uv python@3.12 node@24
+echo 'export PATH="/opt/homebrew/opt/node@24/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+
+python3.12 --version
+uv --version
+node --version
+npm --version
+
+uv sync --locked
+uv run python -m pytest
+uv run python tools/update_snapshots.py --check
+uv run ruff check .
+uv run ruff format --check .
 ```
 
-Use Python 3.11 or newer. The repository uses LF line endings through `.gitattributes`.
+Node.js is a system-level development prerequisite and is not managed by `uv`. The root `package.json` requires Node 18 or newer; local development uses Node 24 LTS.
+
+`uv sync` creates and manages `.venv`, installs the package in editable mode, and installs the default `dev` dependency group. Run project commands through `uv run`; manual virtual-environment activation is optional.
+
+The published package supports Python 3.11 through 3.13. The repository's contributor environment uses Python 3.12 so local development and CI resolve the same interpreter and dependency set. The repository uses LF line endings through `.gitattributes`.
 
 ## Contribution Workflow
 
@@ -33,7 +50,7 @@ Use this workflow when adding detection behavior:
 3. Add a reduced benchmark fixture under `fixtures/benchmark/`.
 4. Add `expected-findings.yaml` with the exact expected rule IDs.
 5. Add a focused regression test in `tests/test_skillgate.py`.
-6. Run `python -m skillgate fixtures summary fixtures/benchmark --format json`.
+6. Run `uv run python -m skillgate fixtures summary fixtures/benchmark --format json`.
 7. Update golden snapshots only when public CLI output intentionally changes.
 8. Update `CHANGELOG.md` and `future_steps.md` for user-facing or roadmap changes.
 
@@ -53,12 +70,12 @@ Each fixture should include:
 
 - A short `README.md`.
 - One or more supported agent files or referenced scripts.
-- `expected-findings.yaml` with the expected rule IDs.
+- `expected-findings.yaml` with the exact expected rule IDs.
 
 Verify fixtures with:
 
 ```bash
-python -m skillgate fixtures summary fixtures/benchmark --format json
+uv run python -m skillgate fixtures summary fixtures/benchmark --format json
 ```
 
 ## Adding Non-Benchmark Comparison Fixtures
@@ -89,13 +106,13 @@ Snapshot outputs are maintained by a repo-local helper rather than the public
 files, run:
 
 ```bash
-python tools/update_snapshots.py --check --artifacts test-outputs/snapshots
+uv run python tools/update_snapshots.py --check --artifacts test-outputs/snapshots
 ```
 
 If the output change is intentional, update the tracked snapshots with:
 
 ```bash
-python tools/update_snapshots.py --accept
+uv run python tools/update_snapshots.py --accept
 ```
 
 ## Documentation

pyproject.toml

@@ -7,7 +7,7 @@ name = "openevalgate-skillgate"
 version = "0.1.1"
 description = "Pre-merge and pre-install trust checks for AI-agent skills and MCP configurations. Scan capabilities, detect risky changes, and block unapproved agent behavior in CI."
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.11,<3.14"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{name = "Chenye Zhu"}]
@@ -53,10 +53,10 @@ dependencies = [
   "typer>=0.12",
 ]
 
-[project.optional-dependencies]
+[dependency-groups]
 dev = [
-  "pytest>=8.0",
-  "ruff>=0.5",
+  "pytest>=8.0,<9",
+  "ruff>=0.5,<1",
 ]
 
 [project.scripts]
@@ -70,6 +70,9 @@ Changelog = "https://github.com/charliechenye/SkillGate/blob/main/CHANGELOG.md"
 Documentation = "https://github.com/charliechenye/SkillGate#readme"
 Security = "https://github.com/charliechenye/SkillGate/security"
 
+[tool.uv]
+default-groups = ["dev"]
+
 [tool.setuptools.packages.find]
 where = ["src"]