# 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.
