Pushing main now rebuilds the site and force-pushes dist/ to pages.
.agents/scripts/publish-pages.sh does the work. It never checks pages
out: it writes a tree straight from dist/ with write-tree and
commit-tree, so the working tree is untouched and a failure halfway
through leaves nothing behind. The commit is parented on the current
pages tip, so the branch keeps its history and a rollback is one
force-push to an earlier commit -- which the script prints before it
pushes.
It refuses to publish when the working tree is dirty, when HEAD is not
main, when HEAD is not the commit being pushed, or when any of the ten
routes is missing or empty in dist/. A build can succeed and still emit a
stub; that is exactly how this site would go down.
The hook guards three ways. AF_PUBLISHING short-circuits it so the
publisher's own push does not re-enter it forever. AF_NO_PUBLISH=1 lets
you push main without publishing. And because git has no post-push hook,
the publish necessarily runs before main lands -- so it first checks that
the remote tip is an ancestor of what is being pushed, and skips
publishing when the push could still be rejected as a non-fast-forward.
Also rewrites the operations guide's rollback section, which still
described merging main into pages with --ff-only. That has not been true
since pages started carrying build output.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
Standard conventional type, and its absence rejected a legitimate lockfile
commit during task 01.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds the agent-facing workspace and a 20-task plan for migrating the site
to Astro. Nothing here implements the refactor; these are briefs, rules and
templates that the task agents read.
- .agents/ holds context, rules, checklists, skills, specialist agents,
component/page/config templates and gate scripts. It is vendor-neutral so
MiniMax, Gemini and Codex can all read it; CLAUDE.md just points at
AGENTS.md.
- .husky/ plus .lintstagedrc.json wire the three gate tiers. gate.sh locks on
the shared git-common-dir so parallel worktrees serialise, and guards the
assertion count in scripts/verify.mjs against a coverage drop.
- plans/astro-refactor/ carries the phase graph, per-task briefs and the
model-routing recommendation.
These files must be tracked before fanning out: a worktree only checks out
tracked files, so an untracked plan is invisible to every agent working in one.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Marcos Paulo