docs: record phase 0 state and next steps
Four task branches are green and unmerged, nothing is pushed, and three plan bugs plus three agent mistakes were fixed along the way. Written so the next session can pick up without re-deriving any of it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
@@ -0,0 +1,120 @@
|
||||
# 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.
|
||||
|
||||
## 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** |
|
||||
|
||||
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.
|
||||
|
||||
## What each task actually produced
|
||||
|
||||
**01 — scaffold (Codex).** Astro 5.5 with `base: '/ai-for-dummies'`, strict TS,
|
||||
`BaseLayout.astro`, `summary.astro` as the single smoke page, lint/format/husky
|
||||
configs, `.gitea/workflows/`, rewritten publishing section in
|
||||
`docs/operations-guide.md`, `hands-on/` copied verbatim into `public/`.
|
||||
Build passes, gate passes, hooks verified live, 42/42 assertions intact.
|
||||
|
||||
**02 — tokens (Gemini).** `src/styles/tokens.css` and `src/styles/base.css`
|
||||
only — 43 lines. It did **not** touch the legacy CSS, deliberately: rewriting
|
||||
`styles.css` would break `verify.mjs`'s exact-string assertions. So the three
|
||||
drifting palettes are now resolved *in the new token layer*, while the live
|
||||
site still runs on the old values. That is the correct scope, but it means the
|
||||
consolidation is not proven visually yet.
|
||||
|
||||
**03 — verification net (Codex).** `.agents/scripts/visual-regression.mjs`,
|
||||
rendered-text snapshots for all 10 routes, and PNG baselines at 4 widths in
|
||||
`.agents/snapshots/before/` and `before-reduced-motion/` (~8 MB, committed on
|
||||
purpose — they are the regression baseline).
|
||||
|
||||
**04 — content schema (MiniMax).** `src/content/config.ts` with eight empty
|
||||
collections and a strict `localized({en, pt})` helper. No content moved; that
|
||||
is tasks 05 and 06.
|
||||
|
||||
## Things I fixed that the plan got wrong
|
||||
|
||||
- `AGENTS.md` listed `package-lock.json` under **Never touch**, meaning never
|
||||
hand-edit. Task 01 read it as never create and shipped with
|
||||
`--package-lock=false`. `npm ci` — which is how every worktree spins up —
|
||||
cannot work without it. Wording corrected; lockfile committed.
|
||||
- The first lockfile was reconstructed from a `node_modules` installed without
|
||||
one, so its entries had no `resolved`/`integrity` and `npm ci` failed with
|
||||
`ETARGET tinyglobby@0.2.17`. Regenerated from a clean install.
|
||||
- `.husky/commit-msg` rejected `build:` and `revert:`. Both are standard
|
||||
conventional types. Added.
|
||||
- `launch.sh` read the agent name with `[a-z-]*`, which cannot match
|
||||
`content-i18n-migrator`. Tasks 04/05/06 silently fell back to
|
||||
`astro-architect`. Fixed to `[a-z0-9-]*` and made it fail loudly instead of
|
||||
guessing. Task 04 was relaunched under the right agent.
|
||||
|
||||
## Things the agents got wrong, and what I did
|
||||
|
||||
- **Task 03 went outside its brief.** It rewrote `scripts/audit-ui.mjs` to ban
|
||||
external CSS dependencies — a sound check that the pre-existing malformed
|
||||
`@font-face` in `styles.css` violates, so it left the gate red for every
|
||||
downstream task. Reverted in `2e79aac`; the snapshot net was kept. **The
|
||||
check should come back once the font decision is made.**
|
||||
- **Task 03 rebased instead of branching**, flattening task 01's merge into
|
||||
four duplicate commits with new SHAs — the same divergent-history trap that
|
||||
broke the `pages` branch. Replayed onto the proper base; task 01 is an
|
||||
ancestor again. Worth adding to `.agents/rules/git-worktrees.md`: **never
|
||||
rebase a task branch onto anything.**
|
||||
- **Task 02 left 29 MB of screenshots in `~/Projects/af-task-02/before/`** —
|
||||
untracked, and in the wrong place (`.agents/snapshots/` is the right one).
|
||||
Its report claims the screenshot box is unticked while the files exist.
|
||||
Delete them or move them; do not commit them where they are.
|
||||
|
||||
## Still open from task 01's own report
|
||||
|
||||
- Real-host smoke test of `/ai-for-dummies/summary/` never ran — the branch is
|
||||
not merged and CI has not published. **This is the #1 production-only failure
|
||||
mode in the whole migration.** Do it before trusting any page work.
|
||||
- No Playwright locally, so screenshot comparison could not run in CI.
|
||||
|
||||
## The decision that is still yours
|
||||
|
||||
`styles.css:1` has an `@font-face` whose `src:` points at a Google Fonts
|
||||
*stylesheet*, not a font file. Manrope and DM Mono have therefore never
|
||||
rendered; the site has always been Arial and generic monospace. Self-hosting
|
||||
them during the migration would silently redesign the site. Task 02 defaulted
|
||||
to matching what renders today. Decide explicitly, then task 19 can restore the
|
||||
external-CSS assertion. See `.agents/context/design-system.md`.
|
||||
|
||||
## Next steps, in order
|
||||
|
||||
1. Verify task 04: `cd ~/Projects/af-task-04 && npm ci --prefer-offline && npm 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.
|
||||
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.
|
||||
|
||||
## Running an agent
|
||||
|
||||
`.agents/scripts/launch.sh <nn> <slug> [--base ref] [--cli codex|agy|mm] [--fg]`
|
||||
|
||||
Routing is automatic: Codex for 01/03/15/16/19, `agy` (Gemini 3.1 Pro) for
|
||||
02/18, `mm` (Claude Code against MiniMax-M3) for the rest. All three launch
|
||||
with permission prompts disabled, because a blocked edit in an unattended run
|
||||
just hangs. Logs land in `.agents/logs/` (gitignored).
|
||||
|
||||
**Task 07 is the routing calibration point.** It is small and easy to judge.
|
||||
Check it before committing to MiniMax for the other twelve.
|
||||
@@ -8,6 +8,9 @@ adding a chapter is a component and a content entry rather than a copy-pasted
|
||||
file — **without changing how the site looks, what it says, or what it costs a
|
||||
visitor to load.**
|
||||
|
||||
**Session state: see [`HANDOVER.md`](HANDOVER.md).** Phase 0 is done and
|
||||
green on four branches; nothing is merged or pushed.
|
||||
|
||||
## Read before starting anything
|
||||
|
||||
| File | Why |
|
||||
|
||||
Reference in New Issue
Block a user