diff --git a/.coderabbit.yaml b/.coderabbit.yaml index c7cd10c..78fccff 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -4,7 +4,7 @@ # # 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-* @@ -12,25 +12,10 @@ 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 ──────────────────────────────────────────────────── diff --git a/.github/actionlint.yaml b/.github/actionlint.yaml new file mode 100644 index 0000000..81be2a5 --- /dev/null +++ b/.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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cd1683d..bd66306 100644 --- a/.github/workflows/ci.yml +++ b/.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/**') diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 15256cb..6b39d38 100644 --- a/.github/workflows/labeler.yml +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index 917a1cf..0a84b48 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,7 +69,7 @@ Invoke via `Agent({ subagent_type: "", prompt: "" })`. | `spec-author` | new `docs/specs/**` file or large spec rewrite | | `contract-author` | new or revised `docs/contracts/-.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.