Update SKILL.md to clarify the process for merging branches and managing worktrees
ci / server (push) Failing after 3m34s
ci / client (push) Successful in 14s

- Revised instructions for merging branches into `main`, emphasizing the importance of removing worktrees before merging.
- Added detailed steps for acquiring a merge lock and checking the main branch status prior to merging.
- Clarified the conditions under which orphaned branches and worktrees are cleaned up.
- Enhanced the final report requirements to include the status of the branch and worktree after completion.
This commit is contained in:
Leonid Pershin
2026-08-20 00:32:57 +03:00
parent 40c450af40
commit a1763eaf68
+73 -16
View File
@@ -107,35 +107,91 @@ git worktree add <путь-в-scratchpad>/wt-phase-25 phase/25-golden-fixtures
Не смог закрыть пункт — оставь ⬜ и напиши в отчёте, что именно не вышло и почему. Полработы с Не смог закрыть пункт — оставь ⬜ и напиши в отчёте, что именно не вышло и почему. Полработы с
честной пометкой лучше, чем ✅ с дырой: следующее ревью её всё равно найдёт, только дороже. честной пометкой лучше, чем ✅ с дырой: следующее ревью её всё равно найдёт, только дороже.
## Кто убирает ветку ## Слить в main и убрать ветку
Ты — нет. Ветка это твой результат: пока её не слили, удалять нечего. Фаза не считается сданной, пока лежит на ветке. Доводишь до `main` сам, тем же запуском.
Порядок такой: Сливать можно **только в основном дереве**: `main` уже занят им, и во второй worktree его не
взять — git прямо откажет. А раз дерево одно на всех агентов, слияния надо выстроить в очередь.
1. Ты убираешь **worktree** — сразу, как закончил: `git worktree remove --force <путь>`. Пока **1. Убери свой worktree.** Пока он держит ветку, слияние и удаление невозможны.
worktree держит ветку, её нельзя ни слить нормально, ни удалить.
2. Пользователь сливает ветку и удаляет её: `git branch -d phase/25-golden-fixtures`. С `-d`, а не ```bash
`-D`: git откажется, если что-то не слито, и это правильная защита. git worktree remove --force <путь-в-scratchpad>/wt-phase-25
3. Ветку забыли удалить — её уберёт следующий запуск скилла, но **только при двух условиях сразу**: ```
фаза стоит ✅ в `README.md` **и** ветка слита в `main`.
**2. Возьми замок слияния** — той же уловкой, что и заявку на фазу:
```bash
git branch merge/lock
```
Упало «already exists» — сливает другой агент. Подожди и повтори; не лезь в дерево, пока замок
чужой. Замок снимается `git branch -D merge/lock` **на всех путях**, включая неудачные: забытый
замок остановит остальных.
**3. Проверь основное дерево, прежде чем трогать.** Оно должно быть на `main` и чистым:
```bash
git -C <корень> status --porcelain
```
Непусто — там работает человек или соседний агент. **Ничего не сливай**, сними замок и скажи об
этом в отчёте. Чужие незакоммиченные правки дороже твоей ветки.
**4. Слей явным коммитом слияния:**
```bash
git -C <корень> merge --no-ff phase/25-golden-fixtures
```
`--no-ff` — чтобы фаза осталась видимой в истории одним куском, а не растворилась в линии.
**5. Конфликты разрешай только те, что понимаешь.** Почти всегда это строка статуса в
`docs/phases/README.md` — там обе стороны правы, надо оставить обе. Конфликт в коде, смысл
которого тебе неясен, — `git merge --abort`, снять замок, оставить ветку и написать в отчёте, с
чем именно она не сходится.
**6. Перепрогони тесты на `main` после слияния.** Две зелёные ветки в сумме бывают красными:
каждая правила своё, а вместе получилось не то. Это единственный способ поймать такое.
Красно — откати слияние и оставь ветку жить:
```bash
git -C <корень> reset --hard ORIG_HEAD
```
**7. Зелено — удали ветку и сними замок:**
```bash
git -C <корень> branch -d phase/25-golden-fixtures
git branch -D merge/lock
```
`-d`, а не `-D`: git откажется удалять неслитое, и это последняя защита от потери работы.
**Не пушь.** Удалёнка есть, но отправка — решение пользователя; делай только если попросили прямо.
**Осиротевшее.** Ветку когда-то забыли удалить — уберёт следующий запуск, но **только при двух
условиях сразу**: фаза стоит ✅ в `README.md` **и** ветка слита в `main`.
```bash ```bash
git branch --merged main --list "phase/*" --format="%(refname:short)" git branch --merged main --list "phase/*" --format="%(refname:short)"
``` ```
Оба условия обязательны, и вот почему: только что созданная ветка ещё не имеет коммитов, а значит Оба условия обязательны, и вот почему: только что созданная ветка ещё не имеет коммитов, а значит
равна `main` и в этот список попадает. Удалить её по одной «слитости» — снести чужую только что равна `main` и в этот список попадает. Удалять по одной «слитости» — снести чужую только что
взятую фазу. Статус ✅ и есть то, что отличает доделанное от начатого. взятую фазу. Статус ✅ и есть то, что отличает доделанное от начатого.
Осиротевшие worktree (агент умер, каталог остался) подчищаются `git worktree prune` — это Каталоги умерших агентов подчищаются `git worktree prune` — записи о несуществующих worktree и так
безопасно, записи о несуществующих каталогах и так мусор. мусор.
## Границы ## Границы
- **Только своя фаза.** Заметил проблему в соседней — строкой в отчёт, не в диф. Реализация, - **Только своя фаза.** Заметил проблему в соседней — строкой в отчёт, не в диф. Реализация,
которая походя переписала полпроекта, невозможна к просмотру глазами. которая походя переписала полпроекта, невозможна к просмотру глазами.
- **Не сливай ветку.** Слияние и порядок веток — решение пользователя, у него их несколько. - **Сливаешь только свою ветку** и только по порядку из «Слить в main и убрать ветку». Чужие ветки
не сливаешь, даже если они выглядят готовыми.
- **Не переставляй чужие статусы** в `README.md` и не трогай чужие 🔄. - **Не переставляй чужие статусы** в `README.md` и не трогай чужие 🔄.
- **Не меняй молча** версию протокола, форму сейва и публичное поведение API — даже когда это - **Не меняй молча** версию протокола, форму сейва и публичное поведение API — даже когда это
очевидно правильно. Если фаза этого требует, так и написано в её задачах. очевидно правильно. Если фаза этого требует, так и написано в её задачах.
@@ -179,7 +235,8 @@ git branch --merged main --list "phase/*" --format="%(refname:short)"
- какие тесты добавлены, списком по одной строке; - какие тесты добавлены, списком по одной строке;
- чем подтверждено: что прогнал и с каким результатом, числа замеров, если были; - чем подтверждено: что прогнал и с каким результатом, числа замеров, если были;
- что осталось незакрытым и почему; - что осталось незакрытым и почему;
- что замечено за границами фазы. - что замечено за границами фазы;
- слита ли ветка в `main` и удалена ли — а если нет, то что помешало.
Ветку не сливаешь и не удаляешь — она и есть результат. Worktree за собой убираешь, иначе ветку Итог запуска — фаза в `main`, ветка удалена, worktree убран, замок снят. Всё, что осталось от
не получится ни слить, ни удалить. работы, — это коммиты и отчёт.