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
+10 -3
View File
@@ -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
+16 -2
View File
@@ -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