73 lines
1.8 KiB
Markdown
73 lines
1.8 KiB
Markdown
# 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.
|
|
|
|
The helper is also covered by the repo-level script test suite:
|
|
|
|
```bash
|
|
pnpm test:scripts
|
|
```
|
|
|
|
That suite runs in CI before the architecture and import/export guardrails so hygiene regressions fail early.
|
|
|
|
## 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.
|