chore(repo): add parallel worktree hygiene guardrail

docs/parallel-worktree-hygiene.md

@@ -0,0 +1,64 @@
+# Parallel Worktree Hygiene
+
+This repository is now opinionated about keeping the worktree reviewable during parallel AI-worker runs.
+
+## Goal
+
+Keep every slice narrow, make unrelated drift visible immediately, and avoid "who touched what?" cleanup phases before reviews or commits.
+
+## Command
+
+Use the root helper:
+
+```bash
+pnpm worktree:hygiene
+```
+
+It prints the current worktree and, when scopes are declared, splits dirty files into:
+
+- `staged`
+- `unstaged`
+- `untracked`
+- `in scope`
+- `outside scope`
+
+## Recommended Flow
+
+Before starting a slice:
+
+```bash
+pnpm worktree:hygiene
+```
+
+When you intentionally work in a narrow area:
+
+```bash
+pnpm worktree:hygiene -- --scope apps/web/e2e --scope apps/web/src/components/timeline --fail-outside-scope
+```
+
+If the worktree is intentionally shared for a moment, keep the signal but suppress the hard failure:
+
+```bash
+pnpm worktree:hygiene -- --scope docs --scope scripts --allow-outside-scope
+```
+
+Before committing:
+
+```bash
+pnpm worktree:hygiene -- --fail-on-dirty
+```
+
+Use `--json` when another tool or agent should consume the output programmatically.
+
+## Parallel-Worker Rules
+
+1. Pick an explicit ownership scope before editing files.
+2. Run the scoped hygiene check before and after each slice.
+3. Do not mix unrelated files into a commit just because they are already dirty.
+4. If `outside-scope` is non-empty, either hand off that scope or finish and commit your own slice first.
+5. Prefer multiple small commits over one shared dirty worktree.
+
+## Notes
+
+- `git status --short` remains the fastest human spot check.
+- `pnpm worktree:hygiene` is the stricter guard when multiple workers operate in parallel.