chore: unify vitest workspace and replace husky with prek

.github/workflows/pr.yaml

@@ -68,11 +68,7 @@ jobs:
           npm install
           npm run build
 
-      - name: Run root unit tests
-        run: npx vitest run
-
-      - name: Run TypeScript unit tests with coverage
-        working-directory: nemoclaw
+      - name: Run all unit tests with coverage
         run: npx vitest run --coverage
 
       - name: Check coverage ratchet

.gitignore

@@ -1,32 +1,44 @@
-node_modules/
-dist/
+# Build artifacts and caches
+*.pyc
 .pytest_cache/
 __pycache__/
-*.pyc
-.DS_Store
-docs/_build/
 coverage/
-vdr-notes/
+dist/
+docs/_build/
+node_modules/
+
+# OS metadata
+.DS_Store
+desktop.ini
+Thumbs.db
+
+# Project-specific
+.claude/
 draft_newsletter_*
+vdr-notes/
 
-# Security: prevent accidental commit of secrets and credentials
-.env
-.env.*
-*.pem
+# Security: secrets, credentials, and keys
+*_ecdsa
+*_ed25519
+*_rsa
+*.jks
 *.key
+*.keystore
 *.p12
+*.pem
 *.pfx
-*.jks
-*.keystore
-.npmrc
+*.tfvars
+.direnv/
+.env
+.env.*
+.envrc
 .netrc
-*_rsa
-*_ed25519
-*_ecdsa
+.npmrc
+.pypirc
 credentials.json
-
-# Security: prevent accidental commit of disclosure drafts
 DRAFT-*.md
-
-# Claude Code worktrees and local state
-.claude/
+key.json
+secrets.json
+secrets.yaml
+service-account*.json
+token.json

.pre-commit-config.yaml

@@ -1,27 +1,22 @@
-# NemoClaw — prek / pre-commit hook configuration (same file; prek is recommended)
+# NemoClaw — prek hook configuration
 # prek: https://github.com/j178/prek — single binary, no Python required for the runner
+# Installed as an npm devDependency (@j178/prek) — available after `npm install`.
+# All git hooks (pre-commit, commit-msg, pre-push) are managed by prek via this file.
+# The "prepare" script in package.json runs `prek install` to wire them up.
 #
-# Local (prek):
-#   brew install prek | uv tool install prek | pip install prek
-#   curl --proto '=https' --tlsv1.2 -LsSf https://github.com/j178/prek/releases/latest/download/prek-installer.sh | sh
-#   prek install
-#   prek run --all-files
-#
-# Alternative — Python pre-commit (reads this file too): https://pre-commit.com
-#   pip install pre-commit && pre-commit install && pre-commit run --all-files
+# Usage:
+#   npx prek install
+#   npx prek run --all-files
 #
 # CI / diff-only runs:
-#   prek run --from-ref <base> --to-ref HEAD
-#   pre-commit run --from-ref <base> --to-ref HEAD
-#
-# Husky (see .husky/pre-commit) runs lint-staged + Vitest on commit; this file adds repo-wide
-# checks (shell, Docker, ruff, eslint in nemoclaw/, SPDX, gitleaks, etc.).
+#   npx prek run --from-ref <base> --to-ref HEAD
 #
-# Priority groups (prek: same priority may run in parallel; stock pre-commit ignores priority):
+# Priority groups (prek runs same-priority hooks in parallel):
 #   0  — General file fixers (whitespace, EOF, line endings)
 #   5  — Shell / Python / TS formatters (shfmt, ruff format, prettier)
 #   6  — Fixes that should follow formatters (ruff check --fix, eslint --fix)
 #  10  — Linters and read-only checks
+#  20  — Project-level checks (vitest)
 
 exclude: ^(nemoclaw/dist/|nemoclaw/node_modules/|docs/_build/|\.venv/|uv\.lock$)
 
@@ -38,6 +33,19 @@ repos:
         args: ["--fix=lf"]
         priority: 0
 
+  # ── Priority 0: reject force-added ignored files ───────────────────────────
+  # Catches `git add -f` of files that .gitignore would normally block.
+  # Single source of truth stays in .gitignore — no duplicate list here.
+  - repo: local
+    hooks:
+      - id: no-force-added-ignored
+        name: Reject force-added ignored files
+        entry: bash -c 'IGNORED=$(git ls-files --ignored --exclude-standard --cached -- "$@") && if [ -n "$IGNORED" ]; then echo "Force-added files that .gitignore would block:" && echo "$IGNORED" && exit 1; fi' --
+        language: system
+        always_run: true
+        pass_filenames: false
+        priority: 0
+
   # ── Priority 5: formatters ────────────────────────────────────────────────
   - repo: https://github.com/scop/pre-commit-shfmt
     rev: v3.12.0-2
@@ -128,7 +136,7 @@ repos:
         name: SPDX license headers
         entry: bash scripts/check-spdx-headers.sh
         language: system
-        files: ^(nemoclaw/src/.*\.ts|nemoclaw-blueprint/.*\.py|.*\.sh|\.husky/.*)$
+        files: ^(nemoclaw/src/.*\.ts|nemoclaw-blueprint/.*\.py|.*\.sh)$
         pass_filenames: true
         priority: 10
 
@@ -139,8 +147,47 @@ repos:
         name: gitleaks (secret scan)
         priority: 10
 
+  # ── Priority 20: project-level checks (pre-commit) ─────────────────────────
+  - repo: local
+    hooks:
+      - id: vitest-plugin
+        name: Vitest (plugin project)
+        entry: npx vitest run --project plugin
+        language: system
+        pass_filenames: false
+        files: ^nemoclaw/
+        priority: 20
+
+  # ── commit-msg hooks ────────────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: commitlint
+        name: commitlint
+        entry: npx commitlint --edit
+        language: system
+        stages: [commit-msg]
+        always_run: true
+
+  # ── pre-push hooks ─────────────────────────────────────────────────────────
+  - repo: local
+    hooks:
+      - id: tsc-check
+        name: TypeScript type check (tsc --noEmit)
+        entry: bash -c 'cd nemoclaw && npx tsc --noEmit'
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+
+      - id: pyright-check
+        name: Pyright (nemoclaw-blueprint)
+        entry: bash -c 'cd nemoclaw-blueprint && uv run --with pyright pyright .'
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]
+
 default_language_version:
   python: python3
 
 fail_fast: false
-minimum_pre_commit_version: "3.0.0"

CONTRIBUTING.md

@@ -57,24 +57,21 @@ These are the primary `make` and `npm` targets for day-to-day development:
 | `cd nemoclaw && npm test` | Run plugin unit tests (Vitest) |
 | `make docs` | Build documentation (Sphinx/MyST) |
 | `make docs-live` | Serve docs locally with auto-rebuild |
-| `prek run --all-files` | Optional: run shared hooks from `.pre-commit-config.yaml` — see below |
+| `npx prek run --all-files` | Run all hooks from `.pre-commit-config.yaml` — see below |
 
-### Optional: prek (pre-commit–compatible)
+### Git hooks (prek)
 
-The repository includes [`.pre-commit-config.yaml`](.pre-commit-config.yaml) for [prek](https://prek.j178.dev/) (recommended) and the Python [`pre-commit`](https://pre-commit.com/) runner — same file, either tool. This **complements** [Husky](.husky/pre-commit), which runs lint-staged and Vitest when you commit.
+All git hooks are managed by [prek](https://prek.j178.dev/), a fast, single-binary pre-commit hook runner installed as a devDependency (`@j178/prek`). The `npm install` step runs `prek install` automatically via the `prepare` script, which wires up the following hooks from [`.pre-commit-config.yaml`](.pre-commit-config.yaml):
 
-Install **prek** (pick one): `brew install prek`, `uv tool install prek`, `pip install prek`, or the [standalone installer](https://prek.j178.dev/installation/). From the repository root:
+| Hook | What runs |
+|------|-----------|
+| **pre-commit** | File fixers, formatters, linters, Vitest (plugin) |
+| **commit-msg** | commitlint (Conventional Commits) |
+| **pre-push** | TypeScript type check (`tsc --noEmit`), Pyright (Python) |
 
-```bash
-prek install
-prek run --all-files   # good check before opening a PR, or after broad edits
-```
-
-`make check` remains the primary documented linter entry point. For scoped runs: `prek run --from-ref <base> --to-ref HEAD` (same flags work with `pre-commit` if you use that instead).
-
-If **prek** is not available, install [`pre-commit`](https://pre-commit.com/) and use `pre-commit install` / `pre-commit run --all-files` with the same config file.
+For a full manual check: `npx prek run --all-files`. For scoped runs: `npx prek run --from-ref <base> --to-ref HEAD`.
 
-If **prek** (or **pre-commit**) is on your `PATH`, [.husky/pre-push](.husky/pre-push) also runs it on the commits you are about to push (merge-base with `@{u}`, or the last commit if no upstream is set). Husky scripts prefer `node_modules/.bin` so type checks and lint-staged work when `npx` is missing from the environment (for example some GUI Git clients).
+`make check` remains the primary documented linter entry point.
 
 ## Project Structure
 

nemoclaw/package.json

@@ -17,8 +17,6 @@
     "lint:fix": "eslint 'src/**/*.ts' --fix",
     "format": "prettier --write 'src/**/*.ts'",
     "format:check": "prettier --check 'src/**/*.ts'",
-    "test": "vitest run",
-    "test:watch": "vitest",
     "check": "npm run lint && npm run format:check && tsc --noEmit",
     "clean": "rm -rf dist/"
   },
@@ -32,15 +30,14 @@
     "@types/node": "^20.19.37",
     "@typescript-eslint/eslint-plugin": "^8.57.0",
     "@typescript-eslint/parser": "^8.57.0",
-    "@vitest/coverage-v8": "^4.1.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "prettier": "^3.8.1",
     "typescript": "^5.4.0",
     "vitest": "^4.1.0"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "files": [
     "dist/",