netcracker/ai-for-dummies

Fork 0

Files

T

Marcos Paulo 3cc5dd7652

verify-and-publish / gate (push) Successful in 3m0s

Details

verify-and-publish / publish (push) Has been skipped

Details

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>

2026-09-05 04:31:44 +00:00

3.2 KiB

Raw Blame History

Rule: git worktrees

This project teaches worktrees. It should use them properly.

One task, one worktree, one agent

# from the main checkout
git worktree add ../af-task-07 -b refactor/task-07-route-cards
cd ../af-task-07
pnpm install --frozen-lockfile

Naming: directory ../af-task-NN, branch refactor/task-NN-<slug>. Both derived from the task file so the mapping is never ambiguous.

Why isolation matters here

The migration runs many agents in parallel over the same small set of files (tokens.css, verify.mjs, astro.config.mjs are contended). Worktrees give each agent its own working directory over one object store — cheap, and no agent can see another's half-finished state.

The failure mode without them: two agents both "fix" verify.mjs, and the second overwrites the first's assertions.

Contended files

These are touched by many tasks. Whoever owns them per the plan is the only writer; everyone else opens an issue in their task report instead of editing:

File	Owner
`src/styles/tokens.css`	`design-system-keeper`
`scripts/verify.mjs`	`verification-engineer`
`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

git fetch origin — then branch from the ref your task file names as its base. Do not assume that base is main.
Read your task file end to end before writing anything.
Confirm your task's dependencies are merged. Task files list them.

Before you finish

pnpm run verify green — without deleting assertions.
The relevant checklist in ../checklists/ complete.
git fetch origin && git merge origin/main, resolve conflicts in your worktree. Merge — never rebase.
Task report: what changed, what you verified, what you did not do.

Cleanup

cd -                                    # back to the main checkout
git worktree remove ../af-task-07
git branch -d refactor/task-07-route-cards

Stale worktrees hold locks and confuse the next agent. git worktree list should be short.

Never

Never work directly on main.
Never force-push a shared branch. The pages branch is the sole exception, and only if CI owns it (see ../context/publishing.md).
Never git add -A from the repository root. This repo has untracked local scratch (.serena/, scripts/inspect.py) that must not be swept into a commit.

3.2 KiB Raw Blame History