ci(validation): add local-first validation framework

.cargo/config.toml

@@ -1,15 +1,19 @@
 [alias]
 xtask = "run -p xtask --"
+validate-bootstrap = "xtask validate bootstrap"
+validate-changed = "xtask validate changed"
+validate-doctor = "xtask validate doctor"
+validate-install-hooks = "xtask validate install-hooks"
 ui-dev = "xtask ui dev"
 ui-build = "xtask ui build"
 ui-harden = "xtask ui-hardening"
 tauri-dev = "xtask tauri dev"
 tauri-build = "xtask tauri build"
 components-build = "xtask components build"
-verify-fast = "xtask verify profile fast"
-verify-repo = "xtask verify profile repo"
-verify-ui = "xtask verify profile ui"
-verify-full = "xtask verify profile full"
+verify-fast = "xtask validate suite core"
+verify-repo = "xtask validate suite governance security core"
+verify-ui = "xtask validate suite ui"
+verify-full = "xtask validate suite full"
 rust-audit = "xtask rust audit"
 rust-clean = "xtask rust clean"
 rust-trace = "xtask rust trace"

.githooks/pre-push

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "${repo_root}"
+
+cargo xtask validate changed --fetch-base

.github/AGENTS.md

@@ -6,7 +6,7 @@
 
 ## When Editing This Plane
 - Update `.github/governance.toml`, templates, and workflow checks together when policy changes.
-- Keep `Governance / validate` authoritative for process enforcement; prefer extending `xtask` over adding one-off shell scripts.
+- Keep `Governance / governance-gate` authoritative for process enforcement; prefer extending `xtask` over adding one-off shell scripts.
 - Re-run `cargo xtask github audit-process` after any template or workflow change.
 
 ## Required Companion Updates

.github/PULL_REQUEST_TEMPLATE.md

@@ -65,9 +65,16 @@ Closes #
 
 - [ ] This branch is based on the current target branch (`origin/main` for normal PRs, the parent branch for stacked PRs).
 - [ ] If this PR is stacked, the PR base points to the parent branch until that parent work merges.
-- [ ] If this PR touches `ui/crates/desktop_runtime`, `ui/crates/system_ui`, or `ui/crates/site/src/generated`, I rebased immediately before requesting merge.
-- [ ] If this PR touches `ui/`, `shared/`, `platform/`, `schemas/`, `.github/`, or `infrastructure/wasmcloud/manifests`, I refreshed from the latest target branch and reran validation immediately before requesting merge.
-- [ ] If this PR updates generated assets or token outputs, I regenerated them after the last rebase.
+- [ ] If this PR touches `ui/crates/desktop_runtime`, `ui/crates/system_ui`, `shared/`, `platform/`, `schemas/`, `.github/`, or `infrastructure/wasmcloud/manifests`, I refreshed from the latest target branch and reran validation immediately before requesting merge.
+- [ ] If this PR changes shell, token, or Tailwind inputs, I regenerated the local derived UI outputs after the last rebase and did not commit repo-generated CSS/token files.
+- [ ] The repository pre-push hook is installed locally, or I am disclosing below why it was bypassed.
+
+## Local Validation
+
+- `cargo xtask validate changed`: pass/fail
+- `cargo xtask github validate-pr-local`: pass/fail
+- `git push --no-verify` used: no/yes
+- If `git push --no-verify` was used, document the incident, rationale, and follow-up issue here.
 
 ## Technical Changes
 

.github/actions/setup-build-environment/action.yml

@@ -14,6 +14,10 @@ inputs:
     description: Node.js version to install. Empty skips Node setup.
     required: false
     default: ""
+  node-version-file:
+    description: File that declares the Node.js version to install. Empty skips version-file setup.
+    required: false
+    default: ""
   node-cache-path:
     description: npm lockfile path used for cache setup. Empty disables npm cache wiring.
     required: false
@@ -22,34 +26,73 @@ inputs:
 runs:
   using: composite
   steps:
+    - name: Validate Node inputs
+      if: ${{ inputs.node-version != '' && inputs.node-version-file != '' }}
+      shell: bash
+      run: |
+        echo "Provide either node-version or node-version-file, not both."
+        exit 1
+
     - name: Setup Node
-      if: ${{ inputs.node-version != '' && inputs.node-cache-path == '' }}
+      if: ${{ inputs.node-version != '' && inputs.node-version-file == '' && inputs.node-cache-path == '' }}
       uses: actions/setup-node@v4
       with:
         node-version: ${{ inputs.node-version }}
 
     - name: Setup Node with npm cache
-      if: ${{ inputs.node-version != '' && inputs.node-cache-path != '' }}
+      if: ${{ inputs.node-version != '' && inputs.node-version-file == '' && inputs.node-cache-path != '' }}
       uses: actions/setup-node@v4
       with:
         node-version: ${{ inputs.node-version }}
         cache: npm
         cache-dependency-path: ${{ inputs.node-cache-path }}
 
-    - name: Install Rust toolchain
-      if: ${{ inputs.rust-components == '' }}
-      uses: dtolnay/rust-toolchain@1.91.1
+    - name: Setup Node from version file
+      if: ${{ inputs.node-version == '' && inputs.node-version-file != '' && inputs.node-cache-path == '' }}
+      uses: actions/setup-node@v4
+      with:
+        node-version-file: ${{ inputs.node-version-file }}
 
-    - name: Install Rust toolchain with components
-      if: ${{ inputs.rust-components != '' }}
-      uses: dtolnay/rust-toolchain@1.91.1
+    - name: Setup Node from version file with npm cache
+      if: ${{ inputs.node-version == '' && inputs.node-version-file != '' && inputs.node-cache-path != '' }}
+      uses: actions/setup-node@v4
       with:
-        components: ${{ inputs.rust-components }}
+        node-version-file: ${{ inputs.node-version-file }}
+        cache: npm
+        cache-dependency-path: ${{ inputs.node-cache-path }}
+
+    - name: Install Rust toolchain
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        toolchain="$(sed -n 's/^channel = \"\\(.*\\)\"$/\\1/p' rust-toolchain.toml)"
+        if [[ -z "${toolchain}" ]]; then
+          echo "failed to resolve Rust toolchain channel from rust-toolchain.toml"
+          exit 1
+        fi
+
+        rustup toolchain install "${toolchain}" --profile minimal --target wasm32-unknown-unknown
+
+        while IFS= read -r component; do
+          [[ -z "${component}" ]] && continue
+          rustup component add --toolchain "${toolchain}" "${component}"
+        done < <(sed -n 's/^components = \\[\\(.*\\)\\]$/\\1/p' rust-toolchain.toml | tr -d '" ' | tr ',' '\n')
+
+        if [[ -n "${{ inputs.rust-components }}" ]]; then
+          IFS=',' read -r -a extra_components <<< "${{ inputs.rust-components }}"
+          for component in "${extra_components[@]}"; do
+            [[ -z "${component}" ]] && continue
+            rustup component add --toolchain "${toolchain}" "${component}"
+          done
+        fi
 
-    - name: Cache cargo
-      uses: Swatinem/rust-cache@v2
+    - name: Cache cargo registry
+      uses: actions/cache@v4
       with:
-        shared-key: ${{ inputs.rust-cache-shared-key }}
-        cache-all-crates: "false"
-        cache-bin: "false"
-        cache-workspace-crates: "false"
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+        key: ${{ runner.os }}-${{ inputs.rust-cache-shared-key }}-${{ hashFiles('Cargo.lock', 'rust-toolchain.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-${{ inputs.rust-cache-shared-key }}-

.github/governance.toml

@@ -11,14 +11,15 @@ branch_name_pattern = "^(feature|fix|infra|docs|refactor|research)/[0-9]+-[a-z0-
 pr_title_pattern = "^(build|chore|ci|docs|feat|fix|perf|refactor|revert|test)\\([a-z0-9][a-z0-9_-]*\\): [a-z0-9].+$"
 # `xtask github sync repo` applies these checks with strict status enforcement so PR heads
 # must be current with the target branch before merge.
-required_status_checks = ["Governance / validate", "CI / pr-gate", "Security / security-gate"]
+required_status_checks = ["Governance / governance-gate", "CI / pr-gate", "Security / security-gate"]
 # `main` requires one approval and code owner review. Stacked PRs should target their
 # parent branch until the base PR merges instead of pointing multiple layers at `main`.
 required_approving_review_count = 1
 dismiss_stale_reviews_on_push = true
 require_code_owner_review = true
 required_review_thread_resolution = true
-# Keep one merge path on `main`; merge queue is enabled separately in GitHub UI.
+# Keep one merge path on `main`; merge queue must remain enabled in GitHub UI and should be the
+# default merge path after local-first validation succeeds.
 allow_auto_merge = true
 allow_squash_merge = true
 allow_merge_commit = false

.github/security-exceptions.toml

@@ -0,0 +1,76 @@
+version = 1
+
+[[exceptions]]
+ids = ["RUSTSEC-2023-0071"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through SurrealDB and jsonwebtoken; there is no fixed upstream version available yet."
+
+[[exceptions]]
+ids = ["RUSTSEC-2021-0046"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "cargo-audit matches the workspace crate name `telemetry` against an unrelated external advisory; this is a false positive for the local crate."
+
+[[exceptions]]
+ids = [
+  "RUSTSEC-2024-0411",
+  "RUSTSEC-2024-0412",
+  "RUSTSEC-2024-0413",
+  "RUSTSEC-2024-0414",
+  "RUSTSEC-2024-0415",
+  "RUSTSEC-2024-0416",
+  "RUSTSEC-2024-0417",
+  "RUSTSEC-2024-0418",
+  "RUSTSEC-2024-0419",
+  "RUSTSEC-2024-0420",
+  "RUSTSEC-2024-0429",
+  "RUSTSEC-2024-0370",
+]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive GTK3 and proc-macro warnings from the current Tauri and WRY desktop host stack; remediation requires upstream migration rather than a local patch."
+
+[[exceptions]]
+ids = ["RUSTSEC-2023-0089"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through the current SurrealDB geo stack; no repo-local replacement is available without a larger upstream dependency move."
+
+[[exceptions]]
+ids = ["RUSTSEC-2025-0141", "RUSTSEC-2026-0002"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through memvid-core and related storage/search dependencies; replacement requires a coordinated dependency upgrade beyond this validation rollout."
+
+[[exceptions]]
+ids = ["RUSTSEC-2025-0057"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through tauri-utils in the current desktop host stack; no repo-local fix is available without an upstream migration."
+
+[[exceptions]]
+ids = ["RUSTSEC-2024-0436"]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through the current Leptos and Tachys macro stack; replacement must follow upstream framework guidance."
+
+[[exceptions]]
+ids = [
+  "RUSTSEC-2025-0075",
+  "RUSTSEC-2025-0080",
+  "RUSTSEC-2025-0081",
+  "RUSTSEC-2025-0098",
+  "RUSTSEC-2025-0100",
+]
+owner = "@justinrayshort"
+issue = 139
+expires = "2026-06-30"
+reason = "Transitive through the current urlpattern and Tauri utility stack; remediation depends on upstream replacements for the archived unicode crates."