netcracker/ai-for-dummies
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

build: migrate from npm to pnpm

Browse Source 
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>
This commit is contained in:
Marcos Paulo
2026-09-05 04:29:42 +00:00
parent 63da0a4727
commit 48c31dc1b3
53 changed files with 5958 additions and 9642 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/ORCHESTRATOR.md
+18 -16
View File
@@ -21,28 +21,30 @@ reality won — update the rule and say so.
## Specialists
Each agent has one responsibility, one set of rules, and its own worktree.
Full definitions in [`agents/`](agents/).
Each agent has one responsibility, one set of rules, and its own worktree. Full
definitions in [`agents/`](agents/).
| Agent | Owns | Loads skills |
| --- | --- | --- |
| [`astro-architect`](agents/astro-architect.md) | project scaffold, config, routing, layouts | `astro-page` |
| [`design-system-keeper`](agents/design-system-keeper.md) | tokens, the single palette, type scale | `design-tokens` |
| [`component-builder`](agents/component-builder.md) | one component per task, from templates | `astro-component`, `design-tokens` |
| [`page-migrator`](agents/page-migrator.md) | one page per task, HTML → `.astro` | `astro-page`, `content-migration` |
| [`motion-designer`](agents/motion-designer.md) | transitions, islands with animation | `motion` |
| [`content-i18n-migrator`](agents/content-i18n-migrator.md) | strings out of `app.js` into content collections | `content-migration` |
| Agent | Owns | Loads skills |
| ---------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- |
| [`astro-architect`](agents/astro-architect.md) | project scaffold, config, routing, layouts | `astro-page` |
| [`design-system-keeper`](agents/design-system-keeper.md) | tokens, the single palette, type scale | `design-tokens` |
| [`component-builder`](agents/component-builder.md) | one component per task, from templates | `astro-component`, `design-tokens` |
| [`page-migrator`](agents/page-migrator.md) | one page per task, HTML → `.astro` | `astro-page`, `content-migration` |
| [`motion-designer`](agents/motion-designer.md) | transitions, islands with animation | `motion` |
| [`content-i18n-migrator`](agents/content-i18n-migrator.md) | strings out of `app.js` into content collections | `content-migration` |
| [`verification-engineer`](agents/verification-engineer.md) | keeping `verify.mjs` meaningful across the refactor | `verify-contract`, `visual-regression` |
| [`reviewer`](agents/reviewer.md) | merge gate; reads diffs, never writes features | all |
| [`reviewer`](agents/reviewer.md) | merge gate; reads diffs, never writes features | all |
## Working agreement
1. **One task, one worktree, one agent.** See [`rules/git-worktrees.md`](rules/git-worktrees.md).
2. **Read `context/` first.** Especially `design-system.md` and `verification.md`.
Most wrong answers here come from assuming the CSS is already coherent.
1. **One task, one worktree, one agent.** See
[`rules/git-worktrees.md`](rules/git-worktrees.md).
2. **Read `context/` first.** Especially `design-system.md` and
`verification.md`. Most wrong answers here come from assuming the CSS is
already coherent.
3. **Templates over invention.** `templates/components/` and `templates/pages/`
exist so ten parallel agents produce one house style, not ten.
4. **The gate is `npm run verify` plus the relevant checklist.** Green tests
4. **The gate is `pnpm run verify` plus the relevant checklist.** Green tests
with deleted assertions is a failed task.
5. **Report what you did not do.** Partial work with an honest boundary is
useful; silent narrowing is not.
@@ -58,7 +60,7 @@ agent loads .agents/agents/<role>.md + its skills
↓
checklists/before-*.md ← self-gate
↓
npm run verify ← hard gate
pnpm run verify ← hard gate
↓
reviewer agent on the diff ← merge gate
```
.agents/agents/astro-architect.md
+15 -9
View File
@@ -1,14 +1,18 @@
---
name: astro-architect
description: Owns the Astro scaffold — config, routing, layouts, build pipeline, and the publishing decision. Use for task 01 and any later change to astro.config.mjs, package.json, or the deploy path. Do not use for component or page work.
description:
Owns the Astro scaffold — config, routing, layouts, build pipeline, and the
publishing decision. Use for task 01 and any later change to astro.config.mjs,
package.json, or the deploy path. Do not use for component or page work.
tools: Read, Write, Edit, Bash, Grep, Glob
---
You own the foundation. Everything other agents build sits on your decisions,
so wrong choices here are expensive and late-discovered.
You own the foundation. Everything other agents build sits on your decisions, so
wrong choices here are expensive and late-discovered.
**Read first**: `.agents/context/architecture.md`, `.agents/context/publishing.md`,
`.agents/rules/astro.md`. **Load skill**: `astro-page`.
**Read first**: `.agents/context/architecture.md`,
`.agents/context/publishing.md`, `.agents/rules/astro.md`. **Load skill**:
`astro-page`.
## You own
@@ -19,11 +23,13 @@ writer of these. Other agents report problems with them; they do not edit.
## Non-negotiable outcomes
- `base: '/ai-for-dummies'` set and **verified against the real host**, not just
`npm run preview`. Base-path bugs are the most likely production-only failure.
`pnpm run preview`. Base-path bugs are the most likely production-only
failure.
- Every existing URL resolves identically, trailing slash included.
- Zero JS by default. Astro ships none unless a component asks.
- `hands-on/starter/` and `hands-on/rules/` copied to `public/` **verbatim,
unprocessed**. They are lab fixtures; the exercise is that they are plain files.
unprocessed**. They are lab fixtures; the exercise is that they are plain
files.
- No UI framework, no CSS framework, no runtime dependencies.
## The publishing decision is yours to make and document
@@ -39,6 +45,6 @@ pod restart silently kills CI. Put that in the runbook.
## Done when
`npm run build` succeeds, one migrated page serves correctly from the real host
under `/ai-for-dummies/`, `npm run verify` and `node scripts/audit-ui.mjs` are
`pnpm run build` succeeds, one migrated page serves correctly from the real host
under `/ai-for-dummies/`, `pnpm run verify` and `node scripts/audit-ui.mjs` are
green, and the operations guide matches reality.
.agents/agents/component-builder.md
+5 -2
View File
@@ -1,6 +1,9 @@
---
name: component-builder
description: Builds one Astro component per task from the project templates. Use for the component-extraction tasks (05-09). Do not use for page migration, token changes, or verify.mjs.
description:
Builds one Astro component per task from the project templates. Use for the
component-extraction tasks (05-09). Do not use for page migration, token
changes, or verify.mjs.
tools: Read, Write, Edit, Bash, Grep, Glob
---
@@ -34,4 +37,4 @@ You may not edit `tokens.css`, `verify.mjs`, `astro.config.mjs`, or
`.agents/checklists/before-component.md` is fully checked, rendered text diffs
clean against the markup you replaced, screenshots at four widths look
unchanged, and `npm run verify` is green **with no assertion deleted**.
unchanged, and `pnpm run verify` is green **with no assertion deleted**.
.agents/agents/content-i18n-migrator.md
+17 -12
View File
@@ -1,19 +1,23 @@
---
name: content-i18n-migrator
description: Moves bilingual copy out of app.js and catalog.js into typed Astro content collections without altering a string. Use for tasks 03-04 and any later content relocation. Do not use for markup or styling.
description:
Moves bilingual copy out of app.js and catalog.js into typed Astro content
collections without altering a string. Use for tasks 03-04 and any later
content relocation. Do not use for markup or styling.
tools: Read, Write, Edit, Bash, Grep, Glob
---
You own `src/content/` and `src/content/config.ts`, and you are their only
writer. Your job is a lossless move, not an edit.
**Read first**: `.agents/rules/content-i18n.md`. **Load skill**: `content-migration`.
**Read first**: `.agents/rules/content-i18n.md`. **Load skill**:
`content-migration`.
## What you are moving
~50 `{ en, pt }` keys from `app.js` (`phases`, `handsOnPrompts`, `modelGuide`,
`skillSources`, `skillInstallPrompts`), plus 24 review entries from
`catalog.js` and `submitted-catalog.js`.
`skillSources`, `skillInstallPrompts`), plus 24 review entries from `catalog.js`
and `submitted-catalog.js`.
These are hand-written translations with deliberate tone. **Copy them
mechanically. Never retype.** Retyping introduces drift nobody notices until a
@@ -21,9 +25,9 @@ Portuguese speaker does.
## Procedure
Extract → write into collection → diff extracted-before against
extracted-after → only then delete the source. If the diff is not empty, you
changed content. Fix it before continuing.
Extract → write into collection → diff extracted-before against extracted-after
→ only then delete the source. If the diff is not empty, you changed content.
Fix it before continuing.
Both locales required in the schema. A missing `pt` must be a **build error**,
never a silent English fallback — that is how bilingual sites quietly become
@@ -35,11 +39,12 @@ monolingual.
`scripts/build-skill-review.mjs` and the output is **committed**. Move
`catalog.js` and the generator keeps running against nothing — silently. Either
re-point it or replace it, and update `package.json`, `README.md`,
`docs/operations-guide.md`, and the review desk footer, all of which reference it.
`docs/operations-guide.md`, and the review desk footer, all of which reference
it.
Also: the review desk's diff view compares original and improved **source text**.
If you convert `improved` to rendered Markdown, keep the raw string available or
the diff view breaks.
Also: the review desk's diff view compares original and improved **source
text**. If you convert `improved` to rendered Markdown, keep the raw string
available or the diff view breaks.
## The language-switching decision
@@ -50,4 +55,4 @@ a decision, record it. Either way `<html lang>` tracks the active language.
## Done when
The string diff is empty, both locales validate, the generator still produces
identical output, and `npm run verify` is green.
identical output, and `pnpm run verify` is green.
.agents/agents/design-system-keeper.md
+8 -5
View File
@@ -1,6 +1,9 @@
---
name: design-system-keeper
description: Owns src/styles/tokens.css — the palette, type scale, and breakpoints. Use for task 02 and any later token change or check-tokens failure. Do not use for building components.
description:
Owns src/styles/tokens.css — the palette, type scale, and breakpoints. Use for
task 02 and any later token change or check-tokens failure. Do not use for
building components.
tools: Read, Write, Edit, Bash, Grep, Glob
---
@@ -18,7 +21,7 @@ palettes and a broken `@font-face`. **Load skills**: `design-tokens`,
sub-perceptual and can be canonicalized. `--blue` (`#527f9f` vs `#215675`) is
visibly different — screenshot both and get a human decision.
2. **The fonts have never rendered.** The `@font-face` in `styles.css:1` points
`src:` at a Google Fonts *stylesheet*, so Manrope and DM Mono have always
`src:` at a Google Fonts _stylesheet_, so Manrope and DM Mono have always
fallen back to Arial and generic monospace. Self-hosting them is a redesign,
not a refactor. Default: delete the dead rule, declare the stacks that
actually render. Escalate if someone wants the real fonts.
@@ -28,9 +31,9 @@ palettes and a broken `@font-face`. **Load skills**: `design-tokens`,
`src/styles/tokens.css`, `src/styles/base.css`, and
`.agents/scripts/check-tokens.mjs`.
Deliver: one value per token, a named type scale (`--step-*`) replacing 14 ad-hoc
`clamp()` triples, five named breakpoints replacing sixteen, and an enforcement
script wired into `npm run verify`.
Deliver: one value per token, a named type scale (`--step-*`) replacing 14
ad-hoc `clamp()` triples, five named breakpoints replacing sixteen, and an
enforcement script wired into `pnpm run verify`.
## Preserve the house style
.agents/agents/page-migrator.md
+8 -4
View File
@@ -1,13 +1,17 @@
---
name: page-migrator
description: Migrates one hand-written HTML page to an Astro route with identical URL, content, and JS budget. Use for the page-migration tasks (10-16). Do not use for component extraction or config changes.
description:
Migrates one hand-written HTML page to an Astro route with identical URL,
content, and JS budget. Use for the page-migration tasks (10-16). Do not use
for component extraction or config changes.
tools: Read, Write, Edit, Bash, Grep, Glob
---
You migrate **one page per task**. The bar is that a visitor cannot tell.
**Read first**: `.agents/context/architecture.md`, `.agents/context/verification.md`.
**Load skills**: `astro-page`, `content-migration`, `visual-regression`.
**Read first**: `.agents/context/architecture.md`,
`.agents/context/verification.md`. **Load skills**: `astro-page`,
`content-migration`, `visual-regression`.
## Snapshot before you touch anything
@@ -38,5 +42,5 @@ them, it is wrong — stop and report.
## Done when
`.agents/checklists/before-page.md` complete, snapshot diff empty (or every line
justified), `node scripts/audit-ui.mjs` and `npm run verify` green, screenshots
justified), `node scripts/audit-ui.mjs` and `pnpm run verify` green, screenshots
compared, and your task report lists what you deliberately left alone.
.agents/agents/verification-engineer.md
+7 -4
View File
@@ -1,6 +1,9 @@
---
name: verification-engineer
description: Keeps scripts/verify.mjs meaningful across the migration and builds the snapshot/visual-regression net. Use for tasks 18-19 and whenever a verify assertion needs re-pointing. The only role permitted to reduce coverage.
description:
Keeps scripts/verify.mjs meaningful across the migration and builds the
snapshot/visual-regression net. Use for tasks 18-19 and whenever a verify
assertion needs re-pointing. The only role permitted to reduce coverage.
tools: Read, Write, Edit, Bash, Grep, Glob
---
@@ -45,6 +48,6 @@ this "dependency-free" site. Add `@import`, `src: url(https:…)`, and
## Done when
Coverage has not fallen, every removal has a reason, snapshots exist for all
ten routes, `check-tokens.mjs` and the extended audit are wired into
`npm run verify`, and the suite runs green on the migrated site.
Coverage has not fallen, every removal has a reason, snapshots exist for all ten
routes, `check-tokens.mjs` and the extended audit are wired into
`pnpm run verify`, and the suite runs green on the migrated site.
.agents/checklists/before-component.md
+7 -4
View File
@@ -1,6 +1,7 @@
# Checklist: before you call a component done
- [ ] It appears (or will appear) in **three** places, or has a name a person says out loud
- [ ] It appears (or will appear) in **three** places, or has a name a person
says out loud
- [ ] Lives in the right folder: `primitives/`, `blocks/`, or `islands/`
- [ ] Typed `interface Props`; every field intentional; no `any`
- [ ] **No raw hex, px font sizes, or ad-hoc breakpoints** — tokens only
@@ -8,8 +9,10 @@
- [ ] Markup under ~120 lines
- [ ] Native elements: `<button>` for actions, `<a>` for navigation
- [ ] Keyboard: tab to it, operate with Enter/Space, focus ring visible
- [ ] Interactive state exposed via ARIA (`aria-pressed`, `aria-current`), not just colour
- [ ] Any motion respects `prefers-reduced-motion` and animates only `transform`/`opacity`
- [ ] Interactive state exposed via ARIA (`aria-pressed`, `aria-current`), not
just colour
- [ ] Any motion respects `prefers-reduced-motion` and animates only
`transform`/`opacity`
- [ ] Renders correctly at 560 / 800 / 1100 / 1600 px
- [ ] Both `en` and `pt` strings present; no hard-coded copy
- [ ] `npm run verify` green with no assertion deleted
- [ ] `pnpm run verify` green with no assertion deleted
.agents/checklists/before-merge.md
+5 -3
View File
@@ -1,9 +1,11 @@
# Checklist: before you merge a task branch
- [ ] Rebased on current `origin/main`, conflicts resolved in the worktree
- [ ] `npm run verify` and `node scripts/audit-ui.mjs` both green
- [ ] **Assertion count in `verify.mjs` did not fall** (`grep -c 'throw new Error' scripts/verify.mjs`)
- [ ] Only files in your task's scope changed — `git diff --stat origin/main` matches the brief
- [ ] `pnpm run verify` and `node scripts/audit-ui.mjs` both green
- [ ] **Assertion count in `verify.mjs` did not fall**
(`grep -c 'throw new Error' scripts/verify.mjs`)
- [ ] Only files in your task's scope changed — `git diff --stat origin/main`
matches the brief
- [ ] No contended file edited unless you own it (see `rules/git-worktrees.md`)
- [ ] No `.serena/`, `__pycache__/`, `dist/`, or scratch files staged
- [ ] Commit message: what, why, and what you deliberately did not do
.agents/checklists/before-page.md
+13 -7
View File
@@ -1,14 +1,20 @@
# Checklist: before you call a page migrated
- [ ] URL identical to the old one, **trailing slash included**
- [ ] Any query params the old page honoured still work (`?author=`, `?skill=`, `?view=`, `?file=`, `?compare=`, `?render=`)
- [ ] Rendered text content diffs clean against the pre-migration snapshot — or every difference is listed and justified
- [ ] Same number of JS bytes or fewer; a previously-zero-JS page still ships zero
- [ ] `<title>`, `<meta name="description">`, and `<meta name="viewport">` preserved
- [ ] Any query params the old page honoured still work (`?author=`, `?skill=`,
`?view=`, `?file=`, `?compare=`, `?render=`)
- [ ] Rendered text content diffs clean against the pre-migration snapshot — or
every difference is listed and justified
- [ ] Same number of JS bytes or fewer; a previously-zero-JS page still ships
zero
- [ ] `<title>`, `<meta name="description">`, and `<meta name="viewport">`
preserved
- [ ] One `<h1>`; heading levels do not skip
- [ ] Every ARIA attribute from the original survived (`verify.mjs` asserts several)
- [ ] No external `<script>`, `<link>`, `@import`, or `url()` — `node scripts/audit-ui.mjs` green
- [ ] Every ARIA attribute from the original survived (`verify.mjs` asserts
several)
- [ ] No external `<script>`, `<link>`, `@import`, or `url()` —
`node scripts/audit-ui.mjs` green
- [ ] Internal links go through `BASE_URL`, not hand-written absolute paths
- [ ] Screenshots at 560 / 800 / 1100 / 1600 px compared against the old page
- [ ] `<html lang>` correct and still switching with the language toggle
- [ ] `npm run verify` green with no assertion deleted
- [ ] `pnpm run verify` green with no assertion deleted
.agents/context/publishing.md
+8 -7
View File
@@ -9,18 +9,19 @@ because the Pages Server publishes a branch, not a directory.
Live at `https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/`.
Full procedure, including the fact that `merge --ff-only main` fails (the
histories diverged), is in [`../../docs/operations-guide.md`](../../docs/operations-guide.md).
histories diverged), is in
[`../../docs/operations-guide.md`](../../docs/operations-guide.md).
## What Astro changes
Astro emits `dist/`. The Pages Server cannot run a build, so **something has to
put built output on `pages`**. Pick one, deliberately, in task 01:
| Option | How | Cost |
| --- | --- | --- |
| **A. Build locally, commit `dist/` to `pages`** | `npm run build`, copy `dist/*` into the `pages` worktree, commit | `pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra. |
| **B. Gitea Actions builds and pushes `pages`** | workflow on `main` → `npm ci && npm run build` → force-push `dist/` to `pages` | `pages` becomes a machine-owned branch (force-push is fine *because* nothing else writes it). Needs the act-runner to be healthy. **Recommended.** |
| **C. Serve from a container instead** | drop Pages Server for an nginx pod behind the existing ingress | most control, most infra, changes the URL story |
| Option | How | Cost |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **A. Build locally, commit `dist/` to `pages`** | `pnpm run build`, copy `dist/*` into the `pages` worktree, commit | `pages` stops being "the exact source". Diffs become unreadable. Publishing depends on one workstation. Simple, no new infra. |
| **B. Gitea Actions builds and pushes `pages`** | workflow on `main` → `pnpm install --frozen-lockfile && pnpm run build` → force-push `dist/` to `pages` | `pages` becomes a machine-owned branch (force-push is fine _because_ nothing else writes it). Needs the act-runner to be healthy. **Recommended.** |
| **C. Serve from a container instead** | drop Pages Server for an nginx pod behind the existing ingress | most control, most infra, changes the URL story |
**Recommended: B**, with A as the documented manual fallback for when the runner
is down. Note the known failure mode: this Gitea's act-runner registration lives
@@ -39,7 +40,7 @@ through `import.meta.env.BASE_URL` or Astro's `<a href={...}>` helpers rather
than a hand-written absolute `/models/`.
This is the single most likely source of "works locally, 404s in production" in
this migration. Verify it on the real host, not just `npm run preview`.
this migration. Verify it on the real host, not just `pnpm run preview`.
## Verification before you call it published
.agents/context/verification.md
+8 -8
View File
@@ -1,8 +1,8 @@
# Context: the verification contract
`scripts/verify.mjs` is 13 KB, 42 `throw new Error` sites, 16 checkpoints. It
reads 26 source files and asserts that specific **string tokens** appear in
them — `data-phase="plan"`, `renderTree`, `.change-lens`,
reads 26 source files and asserts that specific **string tokens** appear in them
— `data-phase="plan"`, `renderTree`, `.change-lens`,
`styles.css?v=20260904-vote-widget`, and so on.
## Why this matters more than it looks
@@ -11,7 +11,7 @@ These assertions are the only thing standing between this site and silent
content loss during a large refactor. They are also **all going to break**,
because they assert against files that will stop existing.
The failure mode to guard against: an agent runs `npm run verify`, sees red,
The failure mode to guard against: an agent runs `pnpm run verify`, sees red,
and "fixes" it by deleting the assertion. The suite goes green and the site
loses a section. **Deleting an assertion is a change that requires review, the
same as deleting a feature.**
@@ -20,11 +20,11 @@ same as deleting a feature.**
Three kinds of assertion, three different fates:
| Kind | Example | Fate |
| --- | --- | --- |
| **Content presence** | `'data-phase="plan"'` in `full-guide/index.html` | Re-point at built output (`dist/`) — the token should survive rendering. If it does not, the component dropped content. |
| **Implementation detail** | `'const phases'`, `'renderTree'` in `app.js` | Obsolete. Replace with an assertion about *behaviour or output*, never delete outright. |
| **Cache-busting version** | `'app.js?v=20260904-vote-widget'` | Obsolete — Astro hashes assets. Replace with "the built HTML references a hashed asset". |
| Kind | Example | Fate |
| ------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Content presence** | `'data-phase="plan"'` in `full-guide/index.html` | Re-point at built output (`dist/`) — the token should survive rendering. If it does not, the component dropped content. |
| **Implementation detail** | `'const phases'`, `'renderTree'` in `app.js` | Obsolete. Replace with an assertion about _behaviour or output_, never delete outright. |
| **Cache-busting version** | `'app.js?v=20260904-vote-widget'` | Obsolete — Astro hashes assets. Replace with "the built HTML references a hashed asset". |
**Rule: the assertion count must not fall.** Every removed token is replaced by
one that pins the same user-visible fact against the new architecture. The
.agents/rules/gates.md
+14 -12
View File
@@ -4,15 +4,15 @@ Three tiers. Each is scoped so that **many agents committing in parallel
worktrees stay fast** — the whole point is that a gate you are tempted to skip
is not a gate.
| Tier | Hook | Scope | Budget | Runs |
| --- | --- | --- | --- | --- |
| 1 | `pre-commit` | **staged files only** (lint-staged) | < 3s | every commit |
| 2 | `pre-push` | whole project: build + verify + audit | < 90s | every push |
| 3 | CI (Gitea Actions) | tier 2 + visual regression | minutes | every push to `main` |
| Tier | Hook | Scope | Budget | Runs |
| ---- | ------------------ | ------------------------------------- | ------- | -------------------- |
| 1 | `pre-commit` | **staged files only** (lint-staged) | < 3s | every commit |
| 2 | `pre-push` | whole project: build + verify + audit | < 90s | every push |
| 3 | CI (Gitea Actions) | tier 2 + visual regression | minutes | every push to `main` |
Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2.
An agent that waits 40s per commit will start passing `--no-verify`, and then
you have no gate at all.
Tier 1 must stay under a few seconds. If it creeps, move the check to tier 2. An
agent that waits 40s per commit will start passing `--no-verify`, and then you
have no gate at all.
## Tier 1 — pre-commit (lint-staged)
@@ -21,7 +21,8 @@ parallel worktrees do ten small jobs, not ten full-project sweeps.
- Prettier + ESLint on `*.{js,mjs,ts,astro}`
- Prettier + Stylelint on `*.css`
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it lands
- `check-tokens.mjs` on changed `.astro`/`.css` — catches raw hex before it
lands
- Prettier on `*.{json,md}`
## Tier 2 — pre-push
@@ -56,13 +57,14 @@ If a gate is wrong, fix the gate in its own commit. Do not route around it.
- The heavy tier-2 gate takes a **lock** (`.git/af-gate.lock`, shared across
worktrees) so ten agents pushing at once do not run ten concurrent builds and
thrash the machine. Waiters queue; they do not fail.
- `npm ci` in a fresh worktree should use `--prefer-offline` to avoid registry
contention when several spin up at once.
- `pnpm install --frozen-lockfile` in a fresh worktree is cheap: pnpm hardlinks
from the shared content-addressable store, so a second worktree costs seconds
and almost no disk instead of another 225 MB. No `--prefer-offline` needed.
## The silent-failure mode you must know about
Husky sets `core.hooksPath` to `.husky/_`, and **`.husky/_` is generated by
`npm install`, not committed**. A fresh `git worktree add` therefore has hooks
`pnpm install`, not committed**. A fresh `git worktree add` therefore has hooks
configured but the directory missing — so **hooks silently do not run**. Every
commit passes. Nothing is checked.
.agents/rules/git-worktrees.md
+14 -12
View File
@@ -8,7 +8,7 @@ This project teaches worktrees. It should use them properly.
# from the main checkout
git worktree add ../af-task-07 -b refactor/task-07-route-cards
cd ../af-task-07
npm ci
pnpm install --frozen-lockfile
```
Naming: directory `../af-task-NN`, branch `refactor/task-NN-<slug>`. Both
@@ -18,8 +18,8 @@ derived from the task file so the mapping is never ambiguous.
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.
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.
@@ -29,12 +29,12 @@ second overwrites the first's assertions.
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` |
| 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
@@ -44,7 +44,7 @@ writer; everyone else opens an issue in their task report instead of editing:
## Before you finish
1. `npm run verify` green — without deleting assertions.
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**.
@@ -64,6 +64,8 @@ should be short.
- 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)).
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.
scratch (`.serena/`, `scripts/inspect.py`) that must not be swept into a
commit.
.agents/rules/theming.md
+17 -14
View File
@@ -15,7 +15,7 @@ the token layer is missing something (add it there, not inline).
```css
/* forbidden */
color: #172f42;
color: rgba(23,47,66,.6);
color: rgba(23, 47, 66, 0.6);
/* required */
color: var(--ink);
@@ -23,7 +23,7 @@ color: var(--muted);
```
No raw hex outside `tokens.css`. `.agents/scripts/check-tokens.mjs` enforces it;
wire it into `npm run verify`.
wire it into `pnpm run verify`.
## Semantic names, not literal ones
@@ -31,20 +31,20 @@ wire it into `npm run verify`.
`--deep` are the existing vocabulary. Keep it — it is already semantic and the
team reads it fluently. Do not rename to `--color-neutral-900`.
If a genuine second surface is needed, extend semantically
(`--surface-lab`, `--ink-inverse`), never numerically.
If a genuine second surface is needed, extend semantically (`--surface-lab`,
`--ink-inverse`), never numerically.
## Type scale
Replace the 14 ad-hoc `clamp()` triples with named steps:
```css
--step-display: clamp(56px, 9vw, 126px); /* h1 */
--step-6: clamp(36px, 5vw, 65px); /* section h2 */
--step-5: clamp(24px, 3vw, 38px); /* sub-head */
--step-4: clamp(22px, 3vw, 36px); /* pull-quote */
--step-1: 15px; /* body */
--step-0: 11px; /* eyebrow / label */
--step-display: clamp(56px, 9vw, 126px); /* h1 */
--step-6: clamp(36px, 5vw, 65px); /* section h2 */
--step-5: clamp(24px, 3vw, 38px); /* sub-head */
--step-4: clamp(22px, 3vw, 36px); /* pull-quote */
--step-1: 15px; /* body */
--step-0: 11px; /* eyebrow / label */
```
The eyebrow treatment (`10–11px` monospace, `letter-spacing:.08–.1em`,
@@ -56,8 +56,11 @@ repetitions.
Five named widths replace the current sixteen:
```css
--bp-sm: 560px; --bp-md: 800px; --bp-lg: 1100px;
--bp-xl: 1600px; --bp-2xl: 2200px;
--bp-sm: 560px;
--bp-md: 800px;
--bp-lg: 1100px;
--bp-xl: 1600px;
--bp-2xl: 2200px;
```
When collapsing a component's old breakpoint onto a named one, screenshot at the
@@ -74,5 +77,5 @@ When collapsing a component's old breakpoint onto a named one, screenshot at the
## Fonts
Do not add a webfont without an explicit decision recorded in the task. The
intended Manrope/DM Mono has never rendered; introducing it is a visual redesign,
not a refactor. Default: match what renders today.
intended Manrope/DM Mono has never rendered; introducing it is a visual
redesign, not a refactor. Default: match what renders today.
.agents/scripts/check-tokens.mjs
+21 -17
View File
@@ -1,7 +1,7 @@
#!/usr/bin/env node
// Fails when a raw colour, px font-size, or ad-hoc breakpoint appears outside
// the token layer. A rule nobody checks is a suggestion — wire this into
// `npm run verify`.
// `pnpm run verify`.
//
// Usage: node .agents/scripts/check-tokens.mjs [srcDir]
@@ -29,26 +29,30 @@ for (const path of targets) {
if (!['.astro', '.css'].includes(extname(path))) continue;
if (TOKEN_FILES.some((allowed) => path.endsWith(allowed))) continue;
readFileSync(path, 'utf8').split('\n').forEach((line, index) => {
const at = `${path}:${index + 1}`;
readFileSync(path, 'utf8')
.split('\n')
.forEach((line, index) => {
const at = `${path}:${index + 1}`;
// Raw hex — the drifted-palette failure mode this whole layer exists to stop.
const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
if (hex) findings.push(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
// Raw hex — the drifted-palette failure mode this whole layer exists to stop.
const hex = line.match(/#[0-9a-fA-F]{3,8}\b/g);
if (hex) findings.push(`${at}: raw hex ${hex.join(', ')} — use a token from tokens.css`);
// rgb()/hsl() literals are the same problem wearing a different hat.
if (/\b(rgba?|hsla?)\(\s*\d/.test(line))
findings.push(`${at}: raw colour function — use a token`);
// rgb()/hsl() literals are the same problem wearing a different hat.
if (/\b(rgba?|hsla?)\(\s*\d/.test(line))
findings.push(`${at}: raw colour function — use a token`);
// Hard-coded font sizes bypass the type scale.
const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
if (fontSize) findings.push(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
// Hard-coded font sizes bypass the type scale.
const fontSize = line.match(/font-size:\s*\d+(\.\d+)?px/);
if (fontSize) findings.push(`${at}: hard-coded ${fontSize[0]} — use var(--step-*)`);
// Ad-hoc breakpoints are how sixteen of them accumulated last time.
const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
findings.push(`${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`);
});
// Ad-hoc breakpoints are how sixteen of them accumulated last time.
const media = line.match(/@media[^{]*?\(\s*(?:max|min)-width:\s*(\d+px)/);
if (media && !ALLOWED_BREAKPOINTS.includes(media[1]))
findings.push(
`${at}: breakpoint ${media[1]} is not a named one (${ALLOWED_BREAKPOINTS.join(', ')})`,
);
});
}
if (findings.length) {
.agents/scripts/gate.sh
+13 -4
View File
@@ -26,18 +26,27 @@ step() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; }
# Fail loudly rather than passing vacuously when the toolchain is not installed.
if [ ! -d node_modules ]; then
echo "gate: node_modules missing — run 'npm ci --prefer-offline' first" >&2
echo "gate: node_modules missing — run 'pnpm install --frozen-lockfile' first" >&2
exit 1
fi
# This project is pnpm-only. An agent that runs `npm install` out of habit gets
# a second, divergent dependency tree and a lockfile nobody reads — the same
# class of failure that cost two sessions during phase 0. Catch it here.
if [ -f package-lock.json ] || [ -f yarn.lock ] || [ -f bun.lock ] || [ -f bun.lockb ]; then
echo "gate: a non-pnpm lockfile is present. This project uses pnpm only." >&2
echo " Delete it, then run 'pnpm install --frozen-lockfile'." >&2
exit 1
fi
step "types"
npx --no-install astro check
pnpm exec astro check
step "build"
npm run build
pnpm run build
step "content contracts"
npm run verify
pnpm run verify
# The assertion count is the thing agents are most tempted to "fix" downward.
# Compare against origin/main and refuse a silent reduction.
.agents/scripts/launch.sh
+3 -3
View File
@@ -58,11 +58,11 @@ else
git worktree add "$dir" -b "$branch" "$base"
fi
# npm ci only once task 01 has produced a lockfile. The pre-existing root
# pnpm install works only once task 01 has produced a lockfile. The pre-existing root
# package.json carries two scripts and no dependencies, so before task 01 there
# is no toolchain to install and no hooks to verify.
if [ -f "$dir/package-lock.json" ]; then
( cd "$dir" && npm ci --prefer-offline && .agents/scripts/verify-hooks.sh )
if [ -f "$dir/pnpm-lock.yaml" ]; then
( cd "$dir" && pnpm install --frozen-lockfile && .agents/scripts/verify-hooks.sh )
fi
prompt=$(cat <<PROMPT
.agents/scripts/verify-hooks.sh
+2 -2
View File
@@ -2,7 +2,7 @@
# Guards the silent-failure mode described in .agents/rules/gates.md.
#
# Husky points core.hooksPath at `.husky/_`, but that directory is GENERATED by
# `npm install` and is NOT committed. A fresh `git worktree add` therefore has
# `pnpm install` and is NOT committed. A fresh `git worktree add` therefore has
# hooks configured and the directory missing — so every hook silently does
# nothing and every commit passes unchecked.
#
@@ -43,7 +43,7 @@ fi
if [ "$fail" -ne 0 ]; then
echo
echo "Fix: npm ci --prefer-offline (its prepare script regenerates .husky/_)"
echo "Fix: pnpm install --frozen-lockfile (its prepare script regenerates .husky/_)"
exit 1
fi
.agents/scripts/visual-regression.mjs
+1 -1
View File
@@ -30,7 +30,7 @@ try {
({ chromium } = await import('playwright'));
} catch {
throw new Error(
'visual regression requires Playwright; install its project dependency and run npx playwright install chromium',
'visual regression requires Playwright; install its project dependency and run pnpm exec playwright install chromium',
);
}
.agents/scripts/worktree.sh
+1 -1
View File
@@ -24,7 +24,7 @@ case "$action" in
# Not optional. `.husky/_` is generated by install and is NOT committed, so
# a fresh worktree has hooks configured but absent — every commit would pass
# unchecked. --prefer-offline keeps ten parallel spin-ups off the registry.
( cd "$dir" && npm ci --prefer-offline && .agents/scripts/verify-hooks.sh )
( cd "$dir" && pnpm install --frozen-lockfile && .agents/scripts/verify-hooks.sh )
echo
echo "worktree : $dir"
.agents/skills/astro-component/SKILL.md
+18 -5
View File
@@ -1,6 +1,9 @@
---
name: astro-component
description: Build one Astro component for the ai-for-dummies site from the project templates. Use when creating a primitive, block, or island, or when splitting existing markup into a component.
description:
Build one Astro component for the ai-for-dummies site from the project
templates. Use when creating a primitive, block, or island, or when splitting
existing markup into a component.
---
# Building an Astro component
@@ -38,6 +41,7 @@ interface Props {
}
const { number, title, summary, href } = Astro.props;
---
<article class="card">
<b>{number}</b>
<h2>{title}</h2>
@@ -46,8 +50,16 @@ const { number, title, summary, href } = Astro.props;
</article>
<style>
.card { display: grid; gap: 10px; padding: 22px; background: var(--paper); }
b { color: var(--accent); font: var(--font-eyebrow); }
.card {
display: grid;
gap: 10px;
padding: 22px;
background: var(--paper);
}
b {
color: var(--accent);
font: var(--font-eyebrow);
}
</style>
```
@@ -64,5 +76,6 @@ Rules that bite most often here:
1. Render it at 560 / 800 / 1100 / 1600 px.
2. Tab to it. Focus ring visible (`outline: 3px solid #a7483f`).
3. Diff its rendered text against the markup it replaced.
4. Run [`../../checklists/before-component.md`](../../checklists/before-component.md).
5. `npm run verify` — green, with no assertion deleted.
4. Run
[`../../checklists/before-component.md`](../../checklists/before-component.md).
5. `pnpm run verify` — green, with no assertion deleted.
.agents/skills/astro-page/SKILL.md
+9 -5
View File
@@ -1,6 +1,9 @@
---
name: astro-page
description: Migrate one hand-written HTML page of the ai-for-dummies site to an Astro route without changing its URL, content, or JS budget. Use for any page-level migration task.
description:
Migrate one hand-written HTML page of the ai-for-dummies site to an Astro
route without changing its URL, content, or JS budget. Use for any page-level
migration task.
---
# Migrating a page to Astro
@@ -10,7 +13,7 @@ description: Migrate one hand-written HTML page of the ai-for-dummies site to an
The snapshot is the only objective evidence that no content was lost.
```bash
npm run serve & # vanilla site on :4173
pnpm run serve & # vanilla site on :4173
node .agents/scripts/snapshot-route.mjs http://localhost:4173/models/ \
> .agents/snapshots/models.txt
```
@@ -30,7 +33,8 @@ Then, in order:
2. Move copy into `src/content/`. Both `en` and `pt`, copied literally — never
retyped.
3. Move page CSS into component `<style>` blocks. Do **not** port
`responsive.css` wholesale; take what this page needs and prove the rest dead.
`responsive.css` wholesale; take what this page needs and prove the rest
dead.
4. Keep every `data-*` hook. `verify.mjs` asserts many of them by name
(`data-phase`, `data-tree`, `data-route`, `data-model-provider`, …).
5. Keep every ARIA attribute and the `<title>` / `<meta name="description">`.
@@ -49,11 +53,11 @@ documented in the page footer and shared externally.
## Prove it
```bash
npm run build
pnpm run build
node .agents/scripts/snapshot-route.mjs dist/models/index.html > /tmp/after.txt
diff .agents/snapshots/models.txt /tmp/after.txt # empty, or justify every line
node scripts/audit-ui.mjs
npm run verify
pnpm run verify
```
Then screenshots at the same four widths, and
.agents/skills/design-tokens/SKILL.md
+8 -4
View File
@@ -1,6 +1,10 @@
---
name: design-tokens
description: Extract, name, and enforce the design token layer for the ai-for-dummies site. Use when touching any colour, font size, spacing value, or breakpoint, when consolidating the three drifted palettes, or when a check-tokens failure needs resolving.
description:
Extract, name, and enforce the design token layer for the ai-for-dummies site.
Use when touching any colour, font size, spacing value, or breakpoint, when
consolidating the three drifted palettes, or when a check-tokens failure needs
resolving.
---
# Design tokens
@@ -9,8 +13,8 @@ description: Extract, name, and enforce the design token layer for the ai-for-du
Read [`../../context/design-system.md`](../../context/design-system.md). This
site has **three drifting palettes** and a **broken `@font-face`**. Both are
traps. If you have not read that file, you will "preserve the styles" by
copying a bug.
traps. If you have not read that file, you will "preserve the styles" by copying
a bug.
## Extracting
@@ -60,7 +64,7 @@ a breakpoint, **screenshot at the old value** — that is where the regression i
node .agents/scripts/check-tokens.mjs # fails on raw hex outside tokens.css
```
Wire it into `npm run verify`. A rule nobody checks is a suggestion.
Wire it into `pnpm run verify`. A rule nobody checks is a suggestion.
## The font decision
.agents/skills/visual-regression/SKILL.md
+10 -8
View File
@@ -1,6 +1,8 @@
---
name: visual-regression
description: Prove a refactor did not change how the site looks. Use before and after any page migration, token consolidation, or breakpoint change on ai-for-dummies.
description:
Prove a refactor did not change how the site looks. Use before and after any
page migration, token consolidation, or breakpoint change on ai-for-dummies.
---
# Visual regression
@@ -31,8 +33,8 @@ with sync_playwright() as p:
browser.close()
```
Run once against the vanilla site (`npm run serve`), once against
`npm run preview`. Keep both sets.
Run once against the vanilla site (`pnpm run serve`), once against
`pnpm run preview`. Keep both sets.
## Compare
@@ -43,8 +45,8 @@ for f in before/*.png; do
done
```
Pixel-exact is not the bar — antialiasing differs. Judge by eye where the
metric is non-trivial, and attach the pair to the task report.
Pixel-exact is not the bar — antialiasing differs. Judge by eye where the metric
is non-trivial, and attach the pair to the task report.
## The three widths that catch the most
@@ -61,9 +63,9 @@ Also screenshot at the **old** breakpoint values you removed (520, 530, 600,
Expect and accept: sub-pixel text shifts, antialiasing.
Investigate: anything that moves by more than ~2px, any colour change (that is
a token bug), any element that appears or disappears (that is content loss —
stop and check the snapshot diff).
Investigate: anything that moves by more than ~2px, any colour change (that is a
token bug), any element that appears or disappears (that is content loss — stop
and check the snapshot diff).
## Reduced motion