Marcos Paulo
48c31dc1b3
Ten git worktrees each carried their own 225 MB node_modules (1.1 GB across five) and paid 11s per `npm ci`. pnpm hardlinks from a shared store: the same five worktrees cost ~250 MB total, and a fresh install is 4s. What changed beyond the mechanical rename: - `overrides` moved to `pnpm-workspace.yaml`. pnpm 11 does not read the `pnpm` field in package.json *or* npm's top-level `overrides`, and it fails silently — the vite/defu/language-server pins would have quietly stopped applying. - Build scripts are blocked by default in pnpm; esbuild and sharp are allowed explicitly via `allowBuilds` (renamed from `onlyBuiltDependencies` in 11). - `packageManager` + `engines` pin the toolchain. - gate.sh rejects a package-lock.json/yarn.lock/bun.lock outright, so an agent running `npm install` out of habit fails loudly instead of building a second, divergent dependency tree. - CI bootstraps pnpm with `npm install --global pnpm@11.25.0` rather than corepack (unbundled as of Node 25) or pnpm/action-setup (this self-hosted act-runner has never run a job; fetching a third-party action is not something to discover on the first one). Two pre-existing CI bugs fixed while in the file: - the gate installed with `npm install --package-lock=false`, which discarded the lockfile the previous session had just fixed. - the visual-regression step imported `playwright`, which is not a dependency, and `visual-regression.mjs` has no compare mode anyway — in CI it overwrote its own baselines and passed unconditionally. Removed with a comment; it comes back when it can diff. The `publish` job is now manual (`workflow_dispatch`). During the migration dist/ holds three HTML files against the live pages branch's ten, so publishing on every push to main would take the site down to a stub. Restore at task 20. HANDOVER.md's incident log still says npm where it describes what happened at the time; that is history, not a missed rename. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
# Rule: git worktrees
|
|
|
|
This project teaches worktrees. It should use them properly.
|
|
|
|
## One task, one worktree, one agent
|
|
|
|
```bash
|
|
# from the main checkout
|
|
git worktree add ../af-task-07 -b refactor/task-07-route-cards
|
|
cd ../af-task-07
|
|
pnpm install --frozen-lockfile
|
|
```
|
|
|
|
Naming: directory `../af-task-NN`, branch `refactor/task-NN-<slug>`. Both
|
|
derived from the task file so the mapping is never ambiguous.
|
|
|
|
## Why isolation matters here
|
|
|
|
The migration runs many agents in parallel over the same small set of files
|
|
(`tokens.css`, `verify.mjs`, `astro.config.mjs` are contended). Worktrees give
|
|
each agent its own working directory over one object store — cheap, and no agent
|
|
can see another's half-finished state.
|
|
|
|
The failure mode without them: two agents both "fix" `verify.mjs`, and the
|
|
second overwrites the first's assertions.
|
|
|
|
## Contended files
|
|
|
|
These are touched by many tasks. Whoever owns them per the plan is the **only**
|
|
writer; everyone else opens an issue in their task report instead of editing:
|
|
|
|
| File | Owner |
|
|
| ---------------------------------- | ----------------------- |
|
|
| `src/styles/tokens.css` | `design-system-keeper` |
|
|
| `scripts/verify.mjs` | `verification-engineer` |
|
|
| `astro.config.mjs`, `package.json` | `astro-architect` |
|
|
| `src/content/config.ts` | `content-i18n-migrator` |
|
|
|
|
## Before you start
|
|
|
|
1. `git fetch origin && git rebase origin/main` — start from current `main`.
|
|
2. Read your task file end to end before writing anything.
|
|
3. Confirm your task's dependencies are merged. Task files list them.
|
|
|
|
## Before you finish
|
|
|
|
1. `pnpm run verify` green — without deleting assertions.
|
|
2. The relevant checklist in [`../checklists/`](../checklists/) complete.
|
|
3. `git rebase origin/main` again, resolve conflicts in your worktree.
|
|
4. Task report: what changed, what you verified, **what you did not do**.
|
|
|
|
## Cleanup
|
|
|
|
```bash
|
|
cd - # back to the main checkout
|
|
git worktree remove ../af-task-07
|
|
git branch -d refactor/task-07-route-cards
|
|
```
|
|
|
|
Stale worktrees hold locks and confuse the next agent. `git worktree list`
|
|
should be short.
|
|
|
|
## Never
|
|
|
|
- Never work directly on `main`.
|
|
- Never force-push a shared branch. The `pages` branch is the sole exception,
|
|
and only if CI owns it (see
|
|
[`../context/publishing.md`](../context/publishing.md)).
|
|
- Never `git add -A` from the repository root. This repo has untracked local
|
|
scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a
|
|
commit.
|