Backpressure

.envrc

@@ -1 +1,2 @@
+watch_file devenv.nix
 use flake . --impure

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+default_stages: [pre-commit]
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-toml
+      - id: check-json
+      - id: check-added-large-files
+      - id: detect-private-key
+      - id: check-executables-have-shebangs
+      - id: check-symlinks
+      - id: check-case-conflict
+  - repo: local
+    hooks:
+      - id: cargo-fmt
+        name: cargo fmt (check)
+        entry: cargo fmt --all -- --check
+        language: system
+        types: [rust]
+        pass_filenames: false
+      - id: cargo-clippy
+        name: cargo clippy (workspace)
+        entry: cargo clippy --workspace --all-targets --all-features -- -D warnings
+        language: system
+        pass_filenames: false
+        files: \.(rs|toml)$
+        stages: [pre-push]
+      - id: cargo-test
+        name: cargo test (workspace)
+        entry: cargo test --workspace
+        language: system
+        pass_filenames: false
+        files: \.(rs|toml)$
+        stages: [pre-push]

AGENTS.md

@@ -14,7 +14,7 @@ SwitchRecomp is a preservation-focused static recompilation research project. Th
 - `README.md` is the project overview and contribution entry point.
 
 ## Build, Test, and Development Commands
-- Dev shell: `devenv shell`
+- Dev shell: `nix develop --impure`
 - Run all tests: `cargo test`
 - Run the sample pipeline:
   - `cargo run -p recomp-cli -- --module samples/minimal/module.json --config samples/minimal/title.toml --out-dir out/minimal`
@@ -32,6 +32,16 @@ SwitchRecomp is a preservation-focused static recompilation research project. Th
 - Test files live under `crates/*/tests/` or inline in modules.
 - Always run the full suite after changes unless the user explicitly says not to.
 
+## Back Pressure Hooks
+Pre-commit hooks provide fast feedback; `prek` is a drop-in replacement that reads the same `.pre-commit-config.yaml`.
+
+- Install hooks: `prek install` or `pre-commit install`.
+- Run on demand: `prek run --all-files` or `pre-commit run --all-files`.
+- macOS note: the Nix dev shell ships `prek` only (to avoid Swift/.NET builds); install `pre-commit` separately if you need it.
+- Configured hooks:
+  - Pre-commit: `trailing-whitespace`, `end-of-file-fixer`, `check-merge-conflict`, `check-yaml`, `check-toml`, `check-json`, `check-added-large-files`, `detect-private-key`, `check-executables-have-shebangs`, `check-symlinks`, `check-case-conflict`, `cargo fmt --check`.
+  - Pre-push: `cargo clippy --workspace --all-targets --all-features -D warnings`, `cargo test --workspace`.
+
 ## Commit & Pull Request Guidelines
 No established commit conventions are present yet. Until standards are set:
 - Use clear, imperative commit messages (e.g., "Add SPEC-070 OS services draft").

README.md

@@ -23,6 +23,17 @@ This repository contains a draft specification set for a Nintendo Switch static
 - The dev environment is managed with Nix + devenv.
 - See `docs/DEVELOPMENT.md` for commands and sample usage.
 
+## Back Pressure Hooks
+These hooks add fast, consistent feedback to keep the repo autonomous and reduce review churn. Hooks are defined in `.pre-commit-config.yaml` and can be run with `prek` (preferred) or `pre-commit`.
+
+- Install hooks: `prek install` or `pre-commit install`.
+- Run on demand: `prek run --all-files` or `pre-commit run --all-files`.
+- macOS note: the Nix dev shell ships `prek` only (to avoid Swift/.NET builds); install `pre-commit` separately if you need it.
+
+Configured hooks:
+- Pre-commit: `trailing-whitespace`, `end-of-file-fixer`, `check-merge-conflict`, `check-yaml`, `check-toml`, `check-json`, `check-added-large-files`, `detect-private-key`, `check-executables-have-shebangs`, `check-symlinks`, `check-case-conflict`, `cargo fmt --check`.
+- Pre-push: `cargo clippy --workspace --all-targets --all-features -D warnings`, `cargo test --workspace`.
+
 ## Specs Update Log
 - 2026-01-29: v0.2 pass started; added hardware baseline details, input/binary format research, OS/services surface notes, and timing/interrupts refinements across specs.
 - 2026-01-29: Added `SPEC-TEMPLATE.md` and expanded `RESEARCH.md` with seed sources.

devenv.nix

@@ -3,9 +3,12 @@
   packages = [
     pkgs.cargo
     pkgs.clippy
+    pkgs.prek
     pkgs.ripgrep
     pkgs.rustc
     pkgs.rustfmt
+  ] ++ pkgs.lib.optionals (!pkgs.stdenv.isDarwin) [
+    pkgs.pre-commit
   ];
 
   cachix.enable = false;

docs/DEVELOPMENT.md

@@ -4,17 +4,44 @@ This project now includes an exploratory Rust workspace and uses Nix + devenv fo
 
 ## Nix + devenv
 - Install `nix` and `devenv`.
-- Enter the shell from the repo root:
+- This repo uses devenv's flake integration. Enter the shell from the repo root:
 
 ```
-devenv shell
+nix develop --impure
 ```
 
 If you use direnv, run:
 ```
 direnv allow
 ```
 
+If `devenv.nix` changes, run `direnv reload` so nix-direnv refreshes the cached shell.
+
+## Back Pressure Hooks (prek + pre-commit)
+Back pressure keeps feedback close to the change. This repo uses pre-commit hooks for fast checks, and `prek` is a drop-in replacement that reads the same `.pre-commit-config.yaml`.
+
+Install hooks (config sets `default_install_hook_types` to `pre-commit` + `pre-push`):
+```
+prek install
+```
+```
+pre-commit install
+```
+
+Run hooks on demand:
+```
+prek run --all-files
+```
+```
+pre-commit run --all-files
+```
+
+macOS note: the Nix dev shell ships `prek` only (to avoid Swift/.NET builds); install `pre-commit` separately if you need it.
+
+Configured hooks:
+- Pre-commit: `trailing-whitespace`, `end-of-file-fixer`, `check-merge-conflict`, `check-yaml`, `check-toml`, `check-json`, `check-added-large-files`, `detect-private-key`, `check-executables-have-shebangs`, `check-symlinks`, `check-case-conflict`, `cargo fmt --check`.
+- Pre-push: `cargo clippy --workspace --all-targets --all-features -D warnings`, `cargo test --workspace`.
+
 ## Workspace Commands
 - Run all tests: