docs(workflow): add pre-commit hooks documentation

Document the pre-commit hook setup, behavior, and rationale for
protecting only main/dev branches while allowing flexibility on
feature branches.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/development/WORKFLOW.md

@@ -205,6 +205,69 @@ test(frontend): add unit tests for ProjectDashboard
 
 ---
 
+## Pre-Commit Hooks
+
+The repository includes pre-commit hooks that enforce validation before commits on protected branches.
+
+### Setup
+
+Enable the hooks by configuring git to use the `.githooks` directory:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+This only needs to be done once per clone.
+
+### What the Hooks Do
+
+When committing to **protected branches** (`main`, `dev`):
+
+| Condition | Action |
+|-----------|--------|
+| Backend files changed | Runs `make validate` in `/backend` |
+| Frontend files changed | Runs `npm run validate` in `/frontend` |
+| No relevant changes | Skips validation |
+
+If validation fails, the commit is blocked with an error message.
+
+When committing to **feature branches**:
+- Validation is skipped (allows WIP commits)
+- A message reminds you to run validation manually if needed
+
+### Why Protected Branches Only?
+
+The hooks only enforce validation on `main` and `dev` for good reasons:
+
+1. **Feature branches are for iteration** - WIP commits, experimentation, and rapid prototyping shouldn't be blocked
+2. **Flexibility during development** - You can commit broken code to your feature branch while debugging
+3. **PRs catch issues** - The merge process ensures validation passes before reaching protected branches
+4. **Manual control** - You can always run `make validate` or `npm run validate` yourself
+
+### Manual Validation
+
+Even on feature branches, you should validate before creating a PR:
+
+```bash
+# Backend
+cd backend && make validate
+
+# Frontend
+cd frontend && npm run validate
+```
+
+### Bypassing Hooks (Emergency Only)
+
+In rare cases where you need to bypass the hook:
+
+```bash
+git commit --no-verify -m "message"
+```
+
+**Use sparingly** - this defeats the purpose of the hooks.
+
+---
+
 ## Documentation Updates
 
 - Keep `docs/architecture/IMPLEMENTATION_ROADMAP.md` updated
@@ -314,8 +377,11 @@ Do NOT use parallel agents when:
 | Action | Command/Location |
 |--------|-----------------|
 | Create branch | `git checkout -b feature/<issue>-<desc>` |
+| Enable pre-commit hooks | `git config core.hooksPath .githooks` |
 | Run backend tests | `IS_TEST=True uv run pytest` |
 | Run frontend tests | `npm test` |
+| Backend validation | `cd backend && make validate` |
+| Frontend validation | `cd frontend && npm run validate` |
 | Check types (backend) | `uv run mypy src/` |
 | Check types (frontend) | `npm run type-check` |
 | Lint (backend) | `uv run ruff check src/` |