60 lines
8.8 KiB
Markdown
60 lines
8.8 KiB
Markdown
# Осмысленные commits по задачам
|
|
|
|
В автоматическом режиме Git управляет runner. Все роли выполняют одну текущую задачу; написание сообщения — служебный артефакт этой задачи, а не разрешение менять Git. Не запускать git add/commit/reset/stash/checkout/push, не менять hooks/config и не обходить проверки. Автоматического push нет.
|
|
|
|
## Границы commits
|
|
|
|
- После executor submit: commit реализации, evidence, handoff и перехода в review. Он ещё не означает acceptance.
|
|
- После reviewer approve: отдельный commit решения review, проверок и перехода в done. Только теперь задача принята.
|
|
- После reject: commit замечаний и возврата в todo; новый executor исправляет только эту задачу.
|
|
- После blocker/аварии: checkpoint ограниченной незавершённой работы и remediation. Сообщение явно говорит, что реализация не принята. Новый агент начинается после checkpoint; работа исходной задачи не смешивается с resolver.
|
|
- Нарушение scope: автоматического commit нет. Runner сохраняет incident, останавливается и оставляет изменения для разбора.
|
|
|
|
Две записи для обычной задачи позволяют независимо увидеть реализацию и результат её проверки. История блокеров также остаётся видимой. Один commit не объединяет несколько agent sessions/задач, кроме неизбежного workflow metadata: например, принятие resolver одновременно возвращает original в очередь.
|
|
|
|
## Сообщение агента
|
|
|
|
До submit/approve/reject создать UTF-8 файл `state/commit_messages/<agent-id>.txt`. После terminal command runner может немедленно завершить процесс: писать сообщение после команды поздно.
|
|
|
|
Формат: English imperative subject длиной 15..100 символов, пустая строка, конкретные `Changes:` и `Validation:`. Полное сообщение максимум 12 000 символов. Тело можно писать по-русски. Не ставить task ID в начале самостоятельно: runner добавляет его и поля Task/Agent/Role/Action/Status/Task title.
|
|
|
|
Пример executor:
|
|
|
|
```text
|
|
Persist per-account archive checkpoints
|
|
|
|
Changes: Сохранение MAM checkpoint изолировано по аккаунтам; добавлена миграция отсутствующего checkpoint.
|
|
Validation: Команда <точная команда> завершилась с exit 0; проверены restart и переключение аккаунта. Проверка с живым сервером не выполнялась.
|
|
```
|
|
|
|
Пример reviewer:
|
|
|
|
```text
|
|
Approve archive checkpoint persistence after restart checks
|
|
|
|
Changes: Принята реализация сохранения checkpoint; приложен независимый review report.
|
|
Validation: Проверены diff и scope; повторена <точная команда>, exit 0. Ограничения внешней проверки перечислены в report.
|
|
```
|
|
|
|
Примеры не являются evidence: заменить их фактическими результатами. «Update files», «Fix stuff», «Task done» и пересказ плана без actual diff недопустимы. Reviewer проверяет смысл сообщения executor вместе с результатом. Инструмент проверяет структуру, но не умеет доказывать истинность текста.
|
|
|
|
Reviewer читает последнюю реализацию своей задачи через read-only `git log --all --grep='^<TASK-ID>:'` и `git show <hash>`, сопоставляет diff, acceptance и evidence. При возврате задачи из blocker также учитывает предыдущие checkpoints этого же ID. Просмотр Git разрешён; изменение Git выполняет только coordinator.
|
|
|
|
При blocker обязательное сообщение не требуется: runner формирует checkpoint из task ID, конкретной причины и статуса. Нельзя задерживать обязательное завершение агента ради Git.
|
|
|
|
## Однократная подготовка Git
|
|
|
|
`git_commits` по умолчанию true даже в старом runner.local.json без этого поля. Нужен Git checkout с первоначальным commit, активной веткой и настроенными user.name/user.email. Foundation сначала сохранить отдельным начальным commit; его создание не выполняется автоматически в пользовательском репозитории. В выделенном новом Web-репозитории это обычные git init/add/commit, выполненные владельцем при подготовке checkout. Не включать реальные secrets или runner.local.json.
|
|
|
|
Перед каждым агентом весь repository working tree и index должны быть чистыми. Это действует и при размещении основы в подкаталоге Apple-репозитория: чужие изменения не включаются автоматически. Не вести параллельные ручные правки в checkout. Hooks и signing выполняются согласно Git config; runner не отключает их. `git_commits: false` доступен для изолированных тестов/явно ручного режима и отключает гарантию commits.
|
|
|
|
Runner проверяет неизменность HEAD, scope, затем явно перечисляет изменённые project paths для staging. Массовый git add всего родительского репозитория не используется. В commit входят исходники и versioned workflow artifacts; `state/runs/`, output logs, runner.local.json и прочие ignored files не входят. Hash commit записывается в `state/runs/<agent-id>/run.json` и summary `last_commit`. Найти историю задачи можно через `git log --all --grep='^S00-001:'`.
|
|
|
|
## Ошибка Git
|
|
|
|
Нет сообщения, hook/signing отказал, HEAD изменён агентом, обнаружены чужие правки или commit не состоялся: runner возвращает `stop: git_error`, exit code 2, и не запускает следующего агента. Статус задачи и изменения сохраняются; даже done в tracker не означает успешный checkpoint. Автоматического reset/очистки/index rollback и обхода hooks нет.
|
|
|
|
Владелец проверяет последний run.json, diff и staged diff, устраняет причину, затем сохраняет именно изменения остановленной сессии обычным commit с подготовленным сообщением (для missing message сначала восстановить правдивый текст по diff/evidence). Если сообщение уже сформировано runner, оно лежит в `state/runs/<agent-id>/commit-message.txt`; использовать `git commit --file <этот путь>`. Убедиться в чистоте checkout и повторно запустить runner. При scope violation сначала разобрать incident и сохранить/отделить изменения; не принимать их общим commit вслепую.
|
|
|
|
В ручном запуске без runner эти автоматические гарантии не действуют: владелец делает соответствующий commit перед передачей следующему агенту. Модель не должна обходить coordinator через самостоятельное управление Git.
|