From 43d1e4a7d2c02ca3959c13bcaf6950cc198cf561 Mon Sep 17 00:00:00 2001 From: t Date: Sat, 19 Sep 2026 10:19:38 -0700 Subject: [PATCH] docs(gate): document the merge-time rust-gate bypass (owner pull_request-mode ruleset actor) --- AGENTS.md | 2 +- docs/development/pre-push-gate.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 3baf79d8a..dc2d52c88 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -142,7 +142,7 @@ npm run serve # Build and run the Rust server **On WSL machines, "the desktop app" means the Windows app.** Always build, install, and launch the Windows Electron app (`npm run electron:build:win` + the NSIS installer) — never a Linux AppImage/deb under WSLg. The Windows build must run as a native Windows process so Cargo produces a native `freshell-server.exe`; drive it from WSL by rsyncing to a Windows-local dir and running Windows npm via `cmd.exe` — see [docs/development/windows-electron-build.md](docs/development/windows-electron-build.md). ### Testing -Pre-push gate: every `git push` runs the cheap local checks (cargo fmt, typecheck, clippy, plus targeted `cargo test` for the changed Rust crates and their dependents when the push touches Rust) filtered by what the push changes — see [docs/development/pre-push-gate.md](docs/development/pre-push-gate.md). Bypass: `git push --no-verify`. Server-side backstop: PRs touching Rust must pass the required `rust-gate` check (workspace `cargo test`, `.github/workflows/rust-tests.yml`); PRs with no Rust changes pass it instantly. +Pre-push gate: every `git push` runs the cheap local checks (cargo fmt, typecheck, clippy, plus targeted `cargo test` for the changed Rust crates and their dependents when the push touches Rust) filtered by what the push changes — see [docs/development/pre-push-gate.md](docs/development/pre-push-gate.md). Bypass: `git push --no-verify`. Server-side backstop: PRs touching Rust must pass the required `rust-gate` check (workspace `cargo test`, `.github/workflows/rust-tests.yml`); PRs with no Rust changes pass it instantly. Merge-time bypass for a red `rust-gate`: `gh pr merge --merge` from the owner account (ruleset `pull_request`-mode bypass actor). Backend fallback policy: never silently fall back from the configured cloud test backend to local — if the cloud path fails, fix it; a local-backend run may substitute only when the cloud path cannot be fixed AND the user explicitly approves. ```bash diff --git a/docs/development/pre-push-gate.md b/docs/development/pre-push-gate.md index 1935f7708..0827b4ddb 100644 --- a/docs/development/pre-push-gate.md +++ b/docs/development/pre-push-gate.md @@ -26,6 +26,7 @@ Vitest/e2e/electron lanes and the real-transport clippy lanes stay with the norm - Bypass (emergencies only): `git push --no-verify` - Disable for one push: `FRESHELL_PREPUSH=0 git push ...` - See routing without running checks: `FRESHELL_PREPUSH_DEBUG=1 git push --dry-run ...` +- Bypass the server-side `rust-gate` (merge-time, PRs only): the owner account is a `pull_request`-mode bypass actor on the "Protect Main - No Direct Push" ruleset, so merging with a red or missing `rust-gate` is just `gh pr merge --merge` from that account — GitHub records it as a ruleset bypass with an audit entry. This is the explicit escape hatch for landing on a red base; it does NOT unlock direct pushes to main. - If a lane's tooling is unavailable it is skipped with an accurate warning (not a failure). The hook self-heals stripped-environment contexts (ssh/agents/IDEs/cron): it sources `~/.nvm/nvm.sh` when `npm` is missing from PATH, and adds `~/.cargo/bin` when `cargo` is missing. ## Setup