docs: forbid rebasing task branches, and record phase 0 as merged
verify-and-publish / gate (push) Successful in 3m0s
verify-and-publish / publish (push) Has been skipped

Task 03 rebased its branch onto task 01 and flattened the merge into four
duplicate commits — but the rule file was *telling* it to: "Before you start:
git rebase origin/main". Replaced with merge-based guidance and an explicit
prohibition, since a rewritten task branch is the same divergent-history trap
that broke the pages branch.

Also corrects gates.md tier 3, which promised screenshot comparison in CI that
is not wired in and cannot be until visual-regression.mjs grows a compare mode.

HANDOVER.md now reflects 01-04 merged, pnpm, and carries forward the review
findings that were noted but deliberately not fixed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Marcos Paulo
2026-09-05 04:31:44 +00:00
parent 48c31dc1b3
commit 3cc5dd7652
4 changed files with 72 additions and 27 deletions
+44 -21
View File
@@ -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 0104 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` | 0104 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, 0811 run four
at a time.
All three are unblocked now that 02 and 04 are in `main`. After 07 lands,
0811 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