Files

T

Marcos Paulo 48c31dc1b3 build: migrate from npm to pnpm

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>

2026-09-05 04:29:42 +00:00

2.5 KiB

Raw Blame History

Rule: git worktrees

This project teaches worktrees. It should use them properly.

One task, one worktree, one agent

# 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

git fetch origin && git rebase origin/main — start from current main.
Read your task file end to end before writing anything.
Confirm your task's dependencies are merged. Task files list them.

Before you finish

pnpm run verify green — without deleting assertions.
The relevant checklist in ../checklists/ complete.
git rebase origin/main again, resolve conflicts in your worktree.
Task report: what changed, what you verified, what you did not do.

Cleanup

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

2.5 KiB Raw Blame History