docs: forbid rebasing task branches, and record phase 0 as merged
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
@@ -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`)
|
||||
|
||||
+10
-3
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user