diff --git a/.agents/checklists/before-merge.md b/.agents/checklists/before-merge.md index cee6b68..ebb6123 100644 --- a/.agents/checklists/before-merge.md +++ b/.agents/checklists/before-merge.md @@ -1,6 +1,7 @@ # Checklist: before you merge a task branch -- [ ] Rebased on current `origin/main`, conflicts resolved in the worktree +- [ ] `origin/main` **merged in** (never rebased), conflicts resolved in the + worktree - [ ] `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`) diff --git a/.agents/rules/gates.md b/.agents/rules/gates.md index ab11c19..f547acc 100644 --- a/.agents/rules/gates.md +++ b/.agents/rules/gates.md @@ -8,7 +8,7 @@ is not a gate. | ---- | ------------------ | ------------------------------------- | ------- | -------------------- | | 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` | +| 3 | CI (Gitea Actions) | tier 2 + lint, on a clean install | 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 @@ -39,8 +39,15 @@ check-tokens.mjs full sweep ## Tier 3 — CI -Tier 2 plus screenshot comparison against `.agents/snapshots/`. Only CI has the -budget for it. +Tier 2 plus `pnpm run lint`, run against a clean +`pnpm install --frozen-lockfile` — which is the part a local worktree cannot +prove. + +Screenshot comparison against `.agents/snapshots/` is **not** wired in yet. +`visual-regression.mjs` can only capture baselines, not diff them, so running it +in CI would overwrite the baselines and pass unconditionally. It also needs +Playwright, which is not a project dependency. Add the step back when the script +grows a compare mode. ## Bypassing diff --git a/.agents/rules/git-worktrees.md b/.agents/rules/git-worktrees.md index 6fe0450..37471ce 100644 --- a/.agents/rules/git-worktrees.md +++ b/.agents/rules/git-worktrees.md @@ -36,9 +36,22 @@ writer; everyone else opens an issue in their task report instead of editing: | `astro.config.mjs`, `package.json` | `astro-architect` | | `src/content/config.ts` | `content-i18n-migrator` | +## Never rebase a task branch + +Not onto `main`, not onto another task branch, not "just to tidy up". A rebase +rewrites every commit with a new SHA, so a branch that others branched from — or +that has already been merged — turns into a duplicate history that no longer +shares an ancestor with the original. Task 03 did this and flattened task 01's +merge into four look-alike commits; it is the same divergent-history trap that +broke the `pages` branch. + +To pick up new work from `main`, **merge it in**: `git merge origin/main`. The +extra merge commit is the price of a history that stays true, and it is cheap. + ## Before you start -1. `git fetch origin && git rebase origin/main` — start from current `main`. +1. `git fetch origin` — then branch from the ref your task file names as its + base. Do not assume that base is `main`. 2. Read your task file end to end before writing anything. 3. Confirm your task's dependencies are merged. Task files list them. @@ -46,7 +59,8 @@ writer; everyone else opens an issue in their task report instead of editing: 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. +3. `git fetch origin && git merge origin/main`, resolve conflicts in your + worktree. **Merge — never rebase.** 4. Task report: what changed, what you verified, **what you did not do**. ## Cleanup diff --git a/plans/astro-refactor/HANDOVER.md b/plans/astro-refactor/HANDOVER.md index 28339f3..5160b4f 100644 --- a/plans/astro-refactor/HANDOVER.md +++ b/plans/astro-refactor/HANDOVER.md @@ -1,21 +1,23 @@ # Handover — Astro refactor, session of 2026-09-05 -Phase 0 is done and green. Phase 1 has not started. Nothing has been pushed; -`main` is **6 commits ahead of `origin/main`**, and no task branch has been -merged into anything. +Phase 0 is done, merged, and green. Tasks 01–04 are all in `main`. The project +now runs on **pnpm**, not npm. Nothing has been pushed: `main` is **23 commits +ahead of `origin/main`**. ## Where the work is -| Branch | Head | Worktree | Gate | -| ----------------------------------- | --------- | --------------------------- | ----------- | -| `main` | `a45aa84` | `~/Projects/ai-for-dummies` | n/a | -| `refactor/task-01-scaffold` | `71021e6` | `~/Projects/af-task-01` | passed | -| `refactor/task-02-tokens` | `c9ec9e3` | `~/Projects/af-task-02` | passed | -| `refactor/task-03-verification-net` | `2e79aac` | `~/Projects/af-task-03` | passed | -| `refactor/task-04-content-schema` | `b554f87` | `~/Projects/af-task-04` | **not run** | +| Branch | Head | State | +| ----------------------------------- | ------------- | ----------------------------------- | +| `main` | see `git log` | 01–04 merged, gate green under pnpm | +| `refactor/task-01-scaffold` | `71021e6` | merged | +| `refactor/task-02-tokens` | `c9ec9e3` | merged | +| `refactor/task-03-verification-net` | `2e79aac` | merged | +| `refactor/task-04-content-schema` | `b554f87` | merged (gate verified before merge) | -02, 03 and 04 all branch from `refactor/task-01-scaffold`, not from `main`. Task -01 must merge to `main` first, then the other three. +All four merged with `--no-ff` and **zero conflicts**. The four worktrees in +`~/Projects/af-task-0*` still exist and still hold npm-era `node_modules`; they +are stale. `~/Projects/af-task-02/before/` still holds 29 MB of misplaced +untracked screenshots — delete or move them before removing that worktree. ## What each task actually produced @@ -92,21 +94,42 @@ external-CSS assertion. See `.agents/context/design-system.md`. ## Next steps, in order -1. Verify task 04: - `cd ~/Projects/af-task-04 && pnpm install --frozen-lockfile && pnpm run gate` -2. Review the four diffs against `.agents/checklists/before-merge.md`. Use a - different model than the one that wrote each — `MODEL-ROUTING.md` says never - review with the author. -3. Merge `refactor/task-01-scaffold` into `main`, then 02, 03, 04. -4. Push `main` — nothing has left this machine yet. +1. **Decide the font question** (see below). It blocks task 19 and it is the + only thing here that needs a human. +2. Push `main` — nothing has left this machine yet. Safe now: the `publish` job + is `workflow_dispatch`-only, so pushing no longer overwrites the live site. + Watch that first CI run; the act-runner has never executed a job. +3. Once CI is green, do the real-host smoke test of `/ai-for-dummies/summary/`. + **This is still the #1 production-only failure mode in the migration** and it + has not been done. Publish manually via the workflow's `publish` input, on a + throwaway basis, or accept the risk until task 20. +4. Clean up the four merged worktrees and branches. 5. Fan out phase 1 and 2: ```bash .agents/scripts/launch.sh 05 content-guide --base main .agents/scripts/launch.sh 06 content-review --base main .agents/scripts/launch.sh 07 primitives --base main ``` - 05 and 06 need 04 merged; 07 needs 02 merged. After 07 lands, 08–11 run four - at a time. + All three are unblocked now that 02 and 04 are in `main`. After 07 lands, + 08–11 run four at a time. + +## Carried over from the phase 0 review + +Found while reviewing the four diffs, none of it blocking, none of it fixed: + +- **`public/hands-on/` is a byte-identical copy of `hands-on/`** with no sync + mechanism. Two trees will drift. Symlink, or copy as a build step. +- **`--bp-*` tokens cannot work.** CSS custom properties do not resolve inside + `@media` queries. The real enforcement is `check-tokens.mjs`'s + `ALLOWED_BREAKPOINTS` allowlist; the variables are decoration and will mislead + whoever writes the first responsive component. +- **`tokens.css` has no font tokens at all**, and the scale skips `--step-2` and + `--step-3`. Downstream of the font decision. +- **`visual-regression.mjs` has no compare mode.** It only captures. It is out + of CI for that reason — see `.agents/rules/gates.md`. +- `src/content/config.ts` uses the legacy `type: 'data'` API. Astro 5 + auto-converts it to a glob loader and it works; prefer explicit + `file()`/`glob()` loaders in `src/content.config.ts` when 05/06 touch it. ## Running an agent