ci: address coderabbit review on PR #1 — perms, sha-pin, spdx, actionlint

.coderabbit.yaml

@@ -4,33 +4,18 @@
 #
 # Spec-driven, AI-first, MIT-forever, Rust monorepo.
 # Constitution: docs/architecture/00-vision.md
-# 12 Laws:      docs/architecture/01-principles.md
+# 15 Laws:      docs/architecture/01-principles.md
 #
 # Companion: docs/guides/coderabbit.md  ·  .claude/skills/coderabbit-*
 
 language: en-US
 early_access: false           # stable schema only; this repo lands ≥100 PRs/day
 enable_free_tier: true        # MIT, public, no paid surface
 
-# Tone — every review is judged against the 12 Laws.
+# Tone — every review is judged against the 15 Laws.
 # CR may be wrong; .claude/skills/coderabbit-triage/SKILL.md allows reject with principle cite.
 tone_instructions: |
-  This is the Nexus Engine repo — open source (MIT), spec-driven, AI-first Rust game engine.
-  Authority order: 12 Laws (docs/architecture/01-principles.md) > spec (docs/specs/**) > contract
-  (docs/contracts/**) > style guide (docs/guides/style-guide.md) > taste.
-  Reject (with reasoning) any suggestion that violates a Law.
-  Every code change MUST cite the spec it implements — flag PRs with no `docs/specs/**` or
-  `docs/contracts/**` reference (Law 2: spec-before-code).
-  Flag any panic!, unwrap(), expect(), or .ok().unwrap() outside `#[cfg(test)]` (Law 6, Law 10).
-  Flag any string-only error (anyhow::anyhow!("..."), format!() returned as Err) outside
-  examples/ and tests/ (Law 10: structured errors only).
-  Flag any println!/eprintln! outside examples/ and tests/ (Law 11: structured telemetry only).
-  Flag any `unsafe` block lacking a `// SAFETY:` paragraph proving the invariants (Law 6).
-  Flag any source file lacking the SPDX MIT header (Law 7).
-  Flag any change to docs/architecture/00-vision.md or docs/architecture/01-principles.md
-  without a paired ADR under docs/architecture/05-adr/ (governance).
-  Prefer concrete fix diffs over abstract advice. Cite line numbers and spec anchors.
-  Skip nits when behavior is unchanged and house style is satisfied.
+  Nexus Engine: MIT, spec-driven, AI-first Rust engine. Authority: docs/architecture/01-principles.md (15 Laws) > docs/specs/** > docs/contracts/**. Reject suggestions violating a Law; cite the Law. Prefer concrete diffs. Skip nits.
 
 reviews:
   profile: assertive                  # default; relax to chill only via ADR
@@ -122,7 +107,7 @@ reviews:
         Reject otherwise. This file is the constitution.
     - path: "docs/architecture/01-principles.md"
       instructions: |
-        Any change to the 12 Laws requires a paired ADR. Reject otherwise. The Laws are
+        Any change to the 15 Laws requires a paired ADR. Reject otherwise. The Laws are
         the binding contract the merge system enforces.
 
     # ── Other docs ────────────────────────────────────────────────────

.github/actionlint.yaml

@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 Nexus Engine contributors
+#
+# actionlint config — register custom self-hosted runner labels so the linter
+# stops flagging them as unknown. Consumed by `actionlint` locally and by
+# CodeRabbit's actionlint integration.
+#
+# Docs: https://github.com/rhysd/actionlint/blob/main/docs/config.md
+
+self-hosted-runner:
+  labels:
+    # Blacksmith managed runners (Phase 1 — Linux only)
+    - blacksmith-4vcpu-ubuntu-2404
+    - blacksmith-4vcpu-ubuntu-2204
+    - blacksmith-2vcpu-ubuntu-2404
+    - blacksmith-8vcpu-ubuntu-2404
+    - blacksmith-16vcpu-ubuntu-2404

.github/workflows/ci.yml

@@ -25,11 +25,11 @@
 #   useblacksmith/setup-rust + useblacksmith/setup-bun are ARCHIVED. Blacksmith
 #   cache works automatically with GitHub's native cache action on Blacksmith
 #   runners, so we use the upstream setup actions:
-#     - actions-rust-lang/setup-rust-toolchain@v1
-#     - oven-sh/setup-bun@v2
+#     - actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
+#     - oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
 #   and Blacksmith's drop-in cache replacements where they still add value:
-#     - useblacksmith/rust-cache@v3   (replaces Swatinem/rust-cache@v2)
-#     - useblacksmith/cache@v5        (replaces actions/cache@v4)
+#     - useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3.0.1   (replaces Swatinem/rust-cache@v2)
+#     - useblacksmith/cache@c5fe29eb0efdf1cf4186b9f7fcbbcbc0cf025662 # v5.0.2        (replaces actions/cache@v4)
 
 name: ci
 
@@ -41,9 +41,9 @@ on:
   workflow_dispatch:
 
 permissions:
+  # Workflow-level default: read-only. Individual jobs elevate when they need
+  # to write (none currently do — artifact upload uses GITHUB_TOKEN with read).
   contents: read
-  pull-requests: write
-  checks: write
 
 concurrency:
   group: ci-${{ github.workflow }}-${{ github.ref }}
@@ -63,10 +63,10 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           components: rustfmt
           cache: false
@@ -81,16 +81,16 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           components: clippy
           cache: false
 
       - name: Cache cargo registry + target (Blacksmith)
-        uses: useblacksmith/rust-cache@v3
+        uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3.0.1
         with:
           shared-key: clippy
           cache-on-failure: true
@@ -105,15 +105,15 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           cache: false
 
       - name: Cache cargo registry + target (Blacksmith)
-        uses: useblacksmith/rust-cache@v3
+        uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3.0.1
         with:
           shared-key: check
           cache-on-failure: true
@@ -128,21 +128,21 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           cache: false
 
       - name: Cache cargo registry + target (Blacksmith)
-        uses: useblacksmith/rust-cache@v3
+        uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3.0.1
         with:
           shared-key: test
           cache-on-failure: true
 
       - name: Install cargo-nextest
-        uses: taiki-e/install-action@v2
+        uses: taiki-e/install-action@7be9fd86bd1707236395105d6e9329dd1511a7e1 # v2.79.0
         with:
           tool: cargo-nextest
 
@@ -151,7 +151,7 @@ jobs:
 
       - name: Upload nextest junit report
         if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: nextest-junit-${{ github.run_id }}
           path: logs/test/nextest-junit.xml
@@ -168,15 +168,15 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           cache: false
 
       - name: Install cargo-deny
-        uses: taiki-e/install-action@v2
+        uses: taiki-e/install-action@7be9fd86bd1707236395105d6e9329dd1511a7e1 # v2.79.0
         with:
           tool: cargo-deny
 
@@ -195,15 +195,15 @@ jobs:
     continue-on-error: true
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Setup Rust toolchain (from rust-toolchain.toml)
-        uses: actions-rust-lang/setup-rust-toolchain@v1
+        uses: actions-rust-lang/setup-rust-toolchain@46268bd060767258de96ed93c1251119784f2ab6 # v1.16.1
         with:
           cache: false
 
       - name: Install cargo-audit
-        uses: taiki-e/install-action@v2
+        uses: taiki-e/install-action@7be9fd86bd1707236395105d6e9329dd1511a7e1 # v2.79.0
         with:
           tool: cargo-audit
 
@@ -220,19 +220,19 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Read pinned Bun version
         id: bun-version
         run: echo "version=$(cat scripts/.bun-version)" >> "$GITHUB_OUTPUT"
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: ${{ steps.bun-version.outputs.version }}
 
       - name: Cache bun install (Blacksmith)
-        uses: useblacksmith/cache@v5
+        uses: useblacksmith/cache@c5fe29eb0efdf1cf4186b9f7fcbbcbc0cf025662 # v5.0.2
         with:
           path: |
             node_modules
@@ -256,19 +256,19 @@ jobs:
     timeout-minutes: 20
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Read pinned Bun version
         id: bun-version
         run: echo "version=$(cat scripts/.bun-version)" >> "$GITHUB_OUTPUT"
 
       - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
         with:
           bun-version: ${{ steps.bun-version.outputs.version }}
 
       - name: Cache bun install (Blacksmith)
-        uses: useblacksmith/cache@v5
+        uses: useblacksmith/cache@c5fe29eb0efdf1cf4186b9f7fcbbcbc0cf025662 # v5.0.2
         with:
           path: |
             node_modules
@@ -295,7 +295,7 @@ jobs:
     timeout-minutes: 10
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
 
       - name: Verify SPDX headers on tracked files
         # Law 7: MIT forever. Every source/docs/script file must carry an
@@ -321,7 +321,9 @@ jobs:
               */.placeholder|*/.bun-version|*/.keep|*/.nvmrc)
                 continue ;;
             esac
-            if ! grep -q -m1 'SPDX-License-Identifier:' "$f"; then
+            # Law 7 intent: header must be near top-of-file, not buried in a
+            # blob somewhere. Restrict to first 15 lines.
+            if ! head -n 15 "$f" | grep -q -m1 'SPDX-License-Identifier:'; then
               missing+=("$f")
             fi
           done < <(git ls-files -z -- 'crates/**' 'scripts/**' 'docs/**' '.github/**')

.github/workflows/labeler.yml

@@ -26,7 +26,7 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: Apply labels from labeler.yml
-        uses: actions/labeler@v5
+        uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5.0.0
         with:
           configuration-path: .github/labeler.yml
           sync-labels: true

CLAUDE.md

@@ -69,7 +69,7 @@ Invoke via `Agent({ subagent_type: "<name>", prompt: "<task>" })`.
 | `spec-author` | new `docs/specs/**` file or large spec rewrite |
 | `contract-author` | new or revised `docs/contracts/<a>-<b>.md` |
 | `adr-author` | log a Nygard-format ADR under `docs/architecture/05-adr/` |
-| `principle-keeper` | audit a PR/file against the 12 laws |
+| `principle-keeper` | audit a PR/file against the 15 laws |
 
 ### Engine domain specialists (one per spec subtree)
 | domain | subagent(s) |
@@ -274,7 +274,7 @@ Full rules: `docs/guides/mastermind-pr-loop.md`. Workflow narrative + SLOs: `doc
 ### CodeRabbit config
 - `/.coderabbit.yaml` — schema: `https://coderabbit.ai/integrations/schema.v2.json`
 - Profile: `assertive`. `request_changes_workflow: true`. Auto-review on `main`.
-- Tone: enforces 12 Laws; rejects suggestions that violate them.
+- Tone: enforces 15 Laws; rejects suggestions that violate them.
 - Path-instructions cover `docs/specs/**`, `docs/contracts/**`, `docs/architecture/05-adr/**`, `crates/**/src/**/*.rs`, `**/*.wgsl`, `crates/**/benches/**`, configs, `.github/workflows/**`.
 - Tools on: shellcheck · markdownlint · github-checks · gitleaks · actionlint · yamllint · hadolint · biome · ruff.