Tooling: pre-commit --fast lane for the check runner

- New `IsFast: true` field on `CheckDefinition`, mirrors `IsSlow` / `CIOnly` / `FreestyleIncompat`.
- 28 checks marked `IsFast`: formatters, non-compiling static linters, Go vet/staticcheck/tests, API server typecheck+tests, html-validate, warn-only metrics.
- `--fast` filters the run to that set. Named `--check` invocations bypass the filter (same escape hatch as `IsSlow` / `CIOnly`).
- `--fast` is mutually exclusive with `--include-slow` / `--only-slow`: combining them errors out at flag-parse time.
- `FilterFastChecks` short-circuits when the flag is off, so main() stays under the gocyclo threshold.
- `AGENTS.md` gains a three-cadence guidance block: `--fast` mid-work (~7 s), full suite before every commit, `--include-slow` before milestone wrap-up. Lists what `--fast` does and doesn't cover.
- Docs in `scripts/check/CLAUDE.md` and `docs/tooling/testing.md` updated to match.

Author: vdavid

AGENTS.md

@@ -103,6 +103,31 @@ Always use the checker script for compilation, linting, formatting, and tests. I
   full list, or multiple `--check` flags.
 - All Rust/Svelte checks: `./scripts/check.sh --rust` or `--svelte`
 - All checks: `./scripts/check.sh`
+
+### When to run what
+
+Three cadences. Pick the one that matches where you are in the work, not the one closest to "done."
+
+- **`./scripts/check.sh --fast` — every few file edits, on a self-imposed rhythm (~7 s).** Don't wait for "before
+  commit"; that's too late, by then a regression is buried under follow-up edits. Run after a small natural unit of
+  work: a function rewritten, a test added, a config touched. Catches roughly half the things the full suite catches,
+  for ~5% of the wall time, so use it liberally. The lane is editorially curated, not derived from timings; mutually
+  exclusive with `--include-slow` / `--only-slow`. Covers:
+  - All formatters (`oxfmt`, `rustfmt`, `gofmt`) and most non-compiling static linters (`cfg-gate`, `log-error-macro`,
+    `error-string-match`, `ipc-enum-camelcase`, `cargo-machete`, `knip`, `import-cycles`, `type-drift`, `stylelint`,
+    `css-unused`, `a11y-contrast`, `a11y-coverage`, `e2e-linux-typecheck`).
+  - Go: `go-vet`, `staticcheck`, `ineffassign`, `misspell`, `gocyclo`, `go-tests`.
+  - API server: `typecheck`, `tests`.
+  - Website: `html-validate` (self-skips when `dist/` is absent).
+  - Warn-only metrics: `file-length`, `claude-md-reminder`, `changelog-links`.
+  - **Does NOT cover**: `clippy`, Rust tests, `cargo-audit`, `cargo-deny`, `jscpd`, `bindings-fresh`, desktop ESLint /
+    `svelte-check` / Svelte tests, website ESLint / typecheck / build / e2e, `docker-build`, or any E2E suite.
+- **`./scripts/check.sh` — before every commit.** The full default suite (everything not marked `IsSlow`). Catches what
+  `--fast` skips: `clippy`, Rust tests, audit/deny, svelte-check, website build, etc. This is the contract that what
+  you're committing won't break CI.
+- **`./scripts/check.sh --include-slow` — before wrapping a milestone, declaring a feature done, or pushing a branch
+  you've been sitting on.** Adds the slow lane on top of the default suite: `desktop-e2e-linux`,
+  `desktop-e2e-playwright`, `rust-tests-linux`, `eslint-typecheck`. Allow ~20 min; this is the gate before "I'm done."
 - **`oxfmt` must always run before you call a task done.** It's monorepo-wide (markdown, YAML, JSON, JS/TS across every
   app) and takes ~1 second, so there's no reason to skip it. It's registered under `AppOther`, which means `--rust` and
   `--svelte` do NOT include it. If you only ran those, CI will catch unformatted markdown / JSON / etc. that you missed.

docs/tooling/testing.md

@@ -150,4 +150,5 @@ race).
 
 The single entry point for all linters, formatters, type checkers, and test runners. Always use it instead of raw
 `cargo`, `pnpm vitest`, `eslint`, etc. Its output is concise and CI-aligned. Per-check: `--check <name>`. By language:
-`--rust` / `--svelte`. Slow checks (E2E, Docker): `--only-slow`. See AGENTS.md "Testing and checking".
+`--rust` / `--svelte`. Fast pre-commit lane (~7 s, curated): `--fast`. Slow checks (E2E, Docker): `--only-slow`. See
+AGENTS.md "Testing and checking" for the three-cadence guidance.

scripts/check/CLAUDE.md

@@ -24,6 +24,9 @@ go run ./scripts/check --include-slow
 # Run only slow checks
 go run ./scripts/check --only-slow
 
+# Run only the curated fast pre-commit lane (~10s)
+go run ./scripts/check --fast
+
 # CI mode (no auto-fixing, stop on first failure)
 go run ./scripts/check --ci --fail-fast
 
@@ -46,6 +49,7 @@ go run ./scripts/check --only-freestyle
 | `--verbose`                 | Show detailed output                                    |
 | `--include-slow`            | Include slow checks (excluded by default)               |
 | `--only-slow`               | Run only slow checks                                    |
+| `--fast`                    | Run only the curated fast pre-commit check set          |
 | `--only-freestyle`          | Run freestyle-compatible checks on a VM (skip the rest) |
 | `--prefer-freestyle`        | Run compat checks on VM + the rest locally in parallel  |
 | `--fail-fast`               | Stop on first failure                                   |
@@ -70,6 +74,7 @@ go run ./scripts/check --only-freestyle
     -> selectChecks()                # filter AllChecks by flags
     -> FilterSlowChecks()            # drop IsSlow=true unless --include-slow or --check used
     -> FilterCIOnlyChecks()          # drop CIOnly=true unless --ci or --check named it
+    -> FilterFastChecks()            # if --fast: keep IsFast=true (or named via --check)
     -> ensurePnpmDependencies()      # pnpm install once at root (skipped for Rust-only runs)
     -> Runner.Run():
         goroutine pool (NumCPU semaphore)
@@ -115,6 +120,12 @@ counted as failed. Dependencies not in the selected run set are treated as satis
 `desktop-e2e-playwright`). Named `--check` invocations implicitly include slow checks
 (`includeSlow = len(checkNames) > 0`).
 
+**Fast lane (`--fast`):** `IsFast: true` marks the curated pre-commit check set: ~28 checks that finish in roughly 10s
+on a warm cache, intended to run before every commit. It's an editorial pick, not a timing-derived list (see Key
+decisions below). Named `--check` invocations bypass the filter so `--fast --check svelte-check` still runs
+svelte-check. Mutually exclusive with `--include-slow` / `--only-slow` — combining them errors out, since the lanes are
+intentionally separate.
+
 **CI-only checks:** `CIOnly: true` marks checks that run only in `--ci` mode (currently: `cargo-udeps`). They're
 silently dropped from local runs (no SKIPPED line) and are not pulled in by `--include-slow` or `--only-slow`. Escape
 hatch: an explicit `--check cargo-udeps` always runs, so you can verify locally before pushing.
@@ -161,6 +172,7 @@ DisplayName:       "eslint", // shown in output
 App:               AppDesktop,
 Tech:              "🎨 Svelte",
 IsSlow:            false,
+IsFast:            false, // true = included in --fast (curated pre-commit lane)
 CIOnly:            false, // true = run only in --ci mode (or explicit --check)
 FreestyleIncompat: true, // can NOT run on freestyle.sh VMs (Rust, Docker)
 DependsOn:         []string{"desktop-svelte-prettier"},
@@ -305,6 +317,14 @@ Orthogonal to `IsSlow`: `--include-slow` and `--only-slow` do NOT pull in CI-onl
 ability to run "all slow checks locally without the CI-only ones"). Negative-sense default (`false` = runs locally)
 matches the other gating fields.
 
+**Decision**: `IsFast` field on `CheckDefinition` and a curated `--fast` pre-commit lane. **Why**: A pre-commit run
+should finish in ~10s so it actually gets used. The list is editorially curated, not derived from CSV timings: warm
+average is what matters, but cold-cache outliers (`cargo-audit` spiking to ~3 min on advisory DB refresh) would silently
+make the lane unreliable on the first run of the day. Mirrors the `IsSlow` / `CIOnly` field pattern (negative-sense
+boolean default, same colocated style). Mutually exclusive with `--include-slow` / `--only-slow` to keep the semantics
+unambiguous: "give me the fast lane" and "give me the slow lane" can't both be true. Named `--check` invocations bypass
+the filter (same escape hatch as `IsSlow` and `CIOnly`).
+
 **Decision**: Skip `pnpm install` when lockfile is unchanged. **Why**: `pnpm install` takes ~20s and pegs all CPUs even
 when deps haven't changed. A marker file (`node_modules/.pnpm-install-marker`) stores `pnpm-lock.yaml`'s mtime after
 each successful install. On the next run, if the mtime matches, install is skipped. The marker lives inside

scripts/check/checks/common.go

@@ -90,6 +90,7 @@ type CheckDefinition struct {
 	App               App
 	Tech              string
 	IsSlow            bool
+	IsFast            bool // true = included in --fast (pre-commit lane). Curated, not derived.
 	CIOnly            bool // true = run only when --ci is set (or when explicitly named via --check)
 	FreestyleIncompat bool // true = can NOT run on freestyle.sh VMs (Rust compilation, Docker, etc.)
 	// NeedsSmb declares that this check requires the smb-consumer Docker stack

scripts/check/checks/registry.go

@@ -13,6 +13,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "📐 Format",
 		FreestyleIncompat: true,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunOxfmt,
 	},
 
@@ -25,6 +26,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: true,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunRustfmt,
 	},
 	{
@@ -65,6 +67,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: true,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunCargoMachete,
 	},
 	{
@@ -96,6 +99,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: true,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunCfgGate,
 	},
 	{
@@ -106,6 +110,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: false,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunLogErrorMacro,
 	},
 	{
@@ -116,6 +121,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: false,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunErrorStringMatch,
 	},
 	{
@@ -136,6 +142,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🦀 Rust",
 		FreestyleIncompat: false,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunIpcEnumCamelCase,
 	},
 	{
@@ -197,6 +204,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   []string{"oxfmt"},
+		IsFast:      true,
 		Run:         RunStylelint,
 	},
 	{
@@ -206,6 +214,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   []string{"desktop-svelte-stylelint"},
+		IsFast:      true,
 		Run:         RunCSSUnused,
 	},
 	{
@@ -215,6 +224,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   []string{"desktop-svelte-stylelint"},
+		IsFast:      true,
 		Run:         RunA11yContrast,
 	},
 	{
@@ -223,6 +233,7 @@ var AllChecks = []CheckDefinition{
 		DisplayName: "a11y-coverage",
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
+		IsFast:      true,
 		Run:         RunA11yCoverage,
 	},
 	{
@@ -241,6 +252,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunImportCycles,
 	},
 	{
@@ -250,6 +262,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunKnip,
 	},
 	{
@@ -259,6 +272,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunTypeDrift,
 	},
 	{
@@ -277,6 +291,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppDesktop,
 		Tech:        "🎨 Svelte",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunDesktopE2ELinuxTypecheck,
 	},
 	{
@@ -344,6 +359,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppWebsite,
 		Tech:        "🚀 Astro",
 		DependsOn:   []string{"website-build"},
+		IsFast:      true,
 		Run:         RunWebsiteHTMLValidate,
 	},
 	{
@@ -370,6 +386,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppApiServer,
 		Tech:        "⸆⸉ TS",
 		DependsOn:   []string{"api-server-eslint"},
+		IsFast:      true,
 		Run:         RunApiServerTypecheck,
 	},
 	{
@@ -378,6 +395,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppApiServer,
 		Tech:        "⸆⸉ TS",
 		DependsOn:   []string{"api-server-typecheck"},
+		IsFast:      true,
 		Run:         RunApiServerTests,
 	},
 
@@ -390,6 +408,7 @@ var AllChecks = []CheckDefinition{
 		Tech:              "🐹 Go",
 		FreestyleIncompat: true,
 		DependsOn:         nil,
+		IsFast:            true,
 		Run:               RunGoFmt,
 	},
 	{
@@ -399,6 +418,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   []string{"scripts-go-gofmt"},
+		IsFast:      true,
 		Run:         RunGoVet,
 	},
 	{
@@ -408,6 +428,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   []string{"scripts-go-gofmt"},
+		IsFast:      true,
 		Run:         RunStaticcheck,
 	},
 	{
@@ -417,6 +438,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   []string{"scripts-go-gofmt"},
+		IsFast:      true,
 		Run:         RunIneffassign,
 	},
 	{
@@ -426,6 +448,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunMisspell,
 	},
 	{
@@ -435,6 +458,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   []string{"scripts-go-gofmt"},
+		IsFast:      true,
 		Run:         RunGocyclo,
 	},
 	{
@@ -462,6 +486,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppScripts,
 		Tech:        "🐹 Go",
 		DependsOn:   []string{"scripts-go-vet"},
+		IsFast:      true,
 		Run:         RunGoTests,
 	},
 
@@ -472,6 +497,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppOther,
 		Tech:        "📏 Metrics",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunFileLength,
 	},
 	{
@@ -480,6 +506,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppOther,
 		Tech:        "📏 Metrics",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunClaudeMdReminder,
 	},
 	{
@@ -489,6 +516,7 @@ var AllChecks = []CheckDefinition{
 		App:         AppOther,
 		Tech:        "🔗 Links",
 		DependsOn:   nil,
+		IsFast:      true,
 		Run:         RunChangelogCommitLinks,
 	},
 }
@@ -592,6 +620,29 @@ func FilterSlowChecks(defs []CheckDefinition, includeSlow bool) []CheckDefinitio
 	return result
 }
 
+// FilterFastChecks keeps only checks marked IsFast (the curated pre-commit
+// lane) when `fast` is true; otherwise returns `defs` unchanged. Checks the
+// user explicitly named via --check bypass the filter, so
+// `--fast --check svelte-check` still runs svelte-check alongside the fast set.
+func FilterFastChecks(defs []CheckDefinition, fast bool, namedChecks []string) []CheckDefinition {
+	if !fast {
+		return defs
+	}
+	named := make(map[string]bool, len(namedChecks))
+	for _, name := range namedChecks {
+		if c := GetCheckByID(name); c != nil {
+			named[c.ID] = true
+		}
+	}
+	var result []CheckDefinition
+	for _, def := range defs {
+		if def.IsFast || named[def.ID] {
+			result = append(result, def)
+		}
+	}
+	return result
+}
+
 // FilterCIOnlyChecks removes CI-only checks unless we're running in CI mode
 // or the user explicitly named them via --check. The named-check escape hatch
 // lets developers verify a CI-only check locally before pushing.