steelmorgan/git-workflow

Процедура работы с Git

Тело вынесено из правила git-workflow. Цель — прозрачная история (один коммит = одна логическая единица работы), откатимость на уровне задачи, аккуратное взаимодействие с генерируемыми артефактами 1С. Guardrail (кто коммитит, запрет удаления) остаётся в правиле — здесь только «как».

Принципы

1. Одна задача — одна ветка. Изоляция задачи на ветке task/TASK-XXX-<slug>, отходящей от родительской ветки (обычно main).
2. Коммит = чекпоинт. Каждая одобренная фаза full-cycle закрепляется коммитом. Это даёт точки восстановления при провале следующей фазы.
3. Squash-merge в родителя. В родительскую ветку задача попадает одним коммитом. История фаз остаётся в task-ветке для постмортема.
4. Сабагенты не коммитят. Право git commit есть только у оркестратора (внутри задачи и финальный merge при выполнении условий из § «Финальный merge») и у пользователя.
5. Маркеры //++agent и git дополняют друг друга. Маркеры дают локальный аудит-след в исходниках (см. agent-code-marking), git — историю во времени. Маркеры в коде НЕ снимаются перед коммитом.
6. Никаких force-push и destructive операций в родительскую ветку. Внутри task-ветки rebase/amend допустимы пока ветка локальная.
7. Запрет на удаление файлов из git без явного разрешения пользователя. Этот принцип критичен — см. отдельный раздел «Запрет на удаление файлов» ниже.

Стратегия веток

Создание ветки задачи

При классификации задачи как medium/complex (full-cycle) оркестратор:

1. Убеждается что рабочее дерево чистое (git status --porcelain пуст). Если нет — это либо незаконченная предыдущая задача (escalate to user), либо ручные правки пользователя (требуют отдельного обсуждения).
2. Стартует с актуальной родительской ветки: git fetch origin && git switch <parent> (например main или master — определяется проектом).
3. Создаёт ветку задачи: git switch -c task/TASK-XXX-<slug>, где <slug> — kebab-case краткое название (максимум 4-5 слов).
4. Фиксирует в orchestrator-context.md имя ветки и SHA родителя на момент отхода.

Quick-fix

Для simple task (см. quick-fix.md: <20 строк, один файл, без новых артефактов) — отдельная ветка НЕ создаётся. Коммит идёт прямо в текущую ветку проекта одним коммитом с маркировкой fix(TASK-XXX): ....

Подзадачи (TASK-XXX.Y)

Если задача делится на нумерованные подзадачи (TASK-103.1, TASK-103.2), каждая подзадача — своя ветка task/TASK-103.1-<slug>, мерджится в main независимо. Если работа неделима — одна ветка task/TASK-103-<slug>, в которой коммиты помечены TASK-103.1, TASK-103.2.

Что коммитим и что нет

MUST коммитить

| Категория | Пути | |-----------|------| | Исходный код | src/xml/**, exts/<extension>/** (кроме защищённых, см. protected-paths) | | Юнит-тесты | exts/TESTS/** | | BDD-сценарии | vanessa-tests/features/**/*.feature, vanessa-tests/support/** | | Документация задачи | tasks/<TASK-XXX>/** целиком — спецификация, технический дизайн, task-breakdown, контексты агентов, финальный отчёт, изображения | | Метаданные конфигурации | ConfigDumpInfo.xml, Configuration.xml — даже если они автогенерируются, это валидная часть Designer-формата | | Маркеры //++agent в коде | Маркеры внутри BSL остаются в коммитах — они часть исходника |

MUST NOT коммитить (.gitignore)

| Категория | Пути | |-----------|------| | Vanessa-артефакты запусков | vanessa-tests/reports/**, vanessa-tests/runs/**, vanessa-tests/allure/** | | Логи runner-ов | **/*.runner.log, **/runner.log, **/temp/** | | Артефакты v8-runner | workPath/**, v8project.local.yaml | | Локальные настройки | .install-session.json (если содержит локальное состояние, а не проектный конфиг) | | Кеши и временные файлы | *.cache, *.tmp, IDE-локальное (.idea/, .vscode/ — на усмотрение проекта) |

Конкретный .gitignore ведётся в проекте; правило фиксирует категории.

Когда коммитит оркестратор

Коммит делается после прохождения approval gate / review для каждой фазы full-cycle.

| Фаза | Что попадает в коммит | Тип сообщения | |------|----------------------|---------------| | Phase 1 (Analyst) после одобрения пользователя | tasks/TASK-XXX/spec.md, .context/analyst-context.md, .context/reviewer-context-spec.md | spec(TASK-XXX) | | Phase 2 (Architect) после одобрения пользователя | tasks/TASK-XXX/technical-design.md, task-breakdown.json, .context/architect-context.md, .context/reviewer-context-arch.md | design(TASK-XXX) | | Phase 3a (Scenario-Author) после Reviewer | vanessa-tests/features/**/*.feature, .context/scenario-author-context.md, .context/reviewer-context-bdd.md | bdd(TASK-XXX): сценарии | | Phase 3b (Developer-Tests) после Reviewer | юнит-тесты в exts/TESTS/**, .context/developer-tests-context.md, .context/reviewer-context-tests.md | test(TASK-XXX) | | Phase 3c (Scenario-Coder) после Reviewer | реализация Vanessa-шагов в vanessa-tests/features/steps/**, vanessa-tests/support/**, .context/scenario-coder-context.md | bdd(TASK-XXX): шаги | | Phase 3d (Developer-Code) после Reviewer | реализация в src/xml/**, exts/<ext>/** (с маркерами //++agent), .context/developer-code-context.md, .context/reviewer-context-code.md | feat(TASK-XXX) / fix / refactor | | Phase 4 (Tester) после Reviewer | дополнительные тесты, .context/tester-context.md, .context/reviewer-context-tester.md | test(TASK-XXX): coverage | | Финальный отчёт | tasks/TASK-XXX/final-report.md | chore(TASK-XXX): final report |

Если фаза не прошла review (BLOCK): правки авторы фазы делают в working tree, без коммита, пока review не закрыт. Только финальная одобренная версия коммитится.

Bug-report от Debugger: отдельный коммит fix(TASK-XXX/debug): <симптом>. После принятия Debugger-фикса.

Формат сообщения коммита

<тип>(TASK-XXX[/phase]): <короткое описание на русском, до 72 символов>

<необязательное расширенное пояснение: чем эта фаза отличается от предыдущей,
какие важные решения зафиксированы. Однострочные коммиты допустимы для простых
случаев.>

Phase: <название фазы из full-cycle>
Agent: <subagent_type, например developer-code>
Co-Authored-By: Claude <[email protected]>

Типы

| Тип | Когда | |-----|-------| | spec | Спецификация (Phase 1) | | design | Технический дизайн (Phase 2) | | bdd | Vanessa-сценарии и шаги (Phase 3a / 3c) | | test | Юнит/интеграционные тесты (Phase 3b / 4) | | feat | Новая функциональность (Phase 3d) | | fix | Исправление бага (Phase 3d или quick-fix) | | refactor | Рефакторинг без изменения поведения | | perf | Оптимизация производительности | | chore | Техдолг, чистка маркеров, финальный отчёт | | docs | Документация (CLAUDE.md, правила, навыки) |

Финальный merge задачи в родительскую ветку

Условия автомержа оркестратором

Оркестратор имеет право выполнить squash-merge в родительскую ветку только при выполнении ВСЕХ условий:

1. cross-provider-review в gate mode вернул verdict: PASS (см. orchestrator.md § 7.2).
2. tasks/TASK-XXX/final-report.md создан и содержит блок cross_provider_review с review_id.
3. Все запуски тестов (unit + Vanessa) в финальной итерации прошли с exit_code=0, raw stdout приложен к финальному отчёту.
4. git status --porcelain чист — нет несохранённых файлов вне scope задачи.
5. Родительская ветка не ушла далеко вперёд: если ушла — оркестратор сначала делает git rebase <parent> в task-ветке и заново гоняет тесты. При конфликтах rebase — escalate to user.

Если хотя бы одно условие не выполнено — оркестратор НЕ мержит, а сообщает пользователю и ждёт его решения. Подтверждения пользователя на сам merge при выполнении всех условий запрашивать НЕ нужно — оркестратор мержит автоматически столько задач, сколько прошло gate.

Команда squash-merge

git switch <parent>
git merge --squash task/TASK-XXX-<slug>
git commit -m "TASK-XXX: <название задачи>

<краткое содержание изменений, 3-5 строк>

Phases completed: 1, 2, 3a, 3b, 3c, 3d, 4
Cross-provider-review: PASS (id=<review_id>)
Task branch: task/TASK-XXX-<slug>

Co-Authored-By: Claude <[email protected]>"

После merge

1. Task-ветка не удаляется в течение минимум 2 недель — на случай отката или разбора полётов.
2. Оркестратор пишет в orchestrator-context.md: MERGED: <merge_sha> → <parent>.
3. Если в проекте есть remote и настроен push — оркестратор НЕ пушит автоматически. Push в remote — решение пользователя.

Запрет на удаление файлов из git

Самая критичная защита от потери работы. Применяется ко всем агентам — оркестратору, сабагентам, debugger'у. Краткий инвариант продублирован в always-on правиле git-workflow; детали процедуры — здесь.

PROHIBITED без явного разрешения пользователя

• git rm <path> — снятие файла с трекинга
• git rm --cached <path> — снятие с трекинга с сохранением в рабочем дереве
• Физическое удаление файла, который был под управлением git (то есть git ls-files его показывает), с последующим включением удаления в коммит
• git reset --hard <commit> за пределами task-ветки или с потерей чужих изменений
• Любая операция, в результате которой git log -- <path> в родителе после merge будет показывать «file deleted»

Когда удаление допустимо

1. Явное письменное разрешение пользователя в текущем диалоге. Без подтверждения «да, удали этот файл» — не удалять. Сохранённые в памяти или CLAUDE.md разрешения НЕ считаются явным разрешением для текущего удаления.
2. Файл попадает под .gitignore и при этом ранее был ошибочно закоммичен. В этом случае — git rm --cached допустим, но оркестратор обязан явно сообщить пользователю «этот файл уходит из git, но остаётся локально, потому что подпадает под .gitignore».
3. Атомарный rename (git mv). Если файл переименовывается / переезжает в другое место — это не удаление, а перемещение, оно прозрачно для истории.

Что делать вместо удаления

| Ситуация | Что делать вместо удаления | |----------|----------------------------| | Старый код больше не нужен | Закомментировать через маркер //--agent (см. agent-code-marking). Физически файл/строки не вырезать | | Артефакт фазы оказался неверным | Перезаписать новой версией. Старая останется в истории коммитов | | Папка задачи кажется неактуальной | НЕ удалять tasks/<TASK-XXX>/. Это аудит-след работы. Если задача отменена — оставить как есть, можно добавить пометку в final-report.md | | Кажется что файл вообще не нужен в репо | Эскалация пользователю с обоснованием. Удаление выполняет ТОЛЬКО пользователь |

Поведение при подозрении на нарушение

Если оркестратор обнаруживает в git status строку D <path> (deleted) ИЛИ строку R <old> -> <new> (rename), которая НЕ инициирована текущей фазой явно:

1. НЕ коммитить изменение
2. Зафиксировать в orchestrator-context.md: SUSPECTED_DELETION: <path>
3. Эскалация пользователю с конкретным вопросом «вы удалили <path> или это побочный эффект?»

Откат

| Сценарий | Действие | |----------|----------| | Фаза не прошла review, ≥3 итерации | Right before BLOCK на 3-й итерации: коммит фазы НЕ делается. Эскалация пользователю. | | Bug в реализации найден после Phase 3d коммита | Отдельный коммит fix(TASK-XXX/debug): ... на той же ветке. | | Задача в родителе оказалась плохой | git revert <squash-sha> в родителе. Один revert убирает задачу целиком. | | Задача брошена в середине | Ветка остаётся как есть. Опционально — переименовать в abandoned/TASK-XXX-<slug>. | | Нужно переделать Phase N с нуля | git reset --hard <commit_phase_N-1> в task-ветке, переделать. |

Параллельные фазы (3a и 3b)

Phase 3a (Scenario-Author) и Phase 3b (Developer-Tests) выполняются параллельно. Оркестратор последовательно коммитит результаты: сначала тот, кто закончил первым, потом второй. Если они затронули общие файлы (что не должно быть по дизайну — 3a пишет .feature, 3b пишет .bsl) — это сигнал к выяснению, кто-то вышел за рамки своей фазы.

Что НЕ делать (анти-практики)

| Анти-практика | Почему плохо | |---------------|--------------| | Сабагент сам делает git commit | Сабагент не видит весь scope фазы, может закоммитить мусор. Право коммита — у оркестратора. | | Коммит «обновление ConfigDumpInfo» отдельным коммитом | ConfigDumpInfo.xml меняется при любой выгрузке, должен идти в коммите той фазы, которая его сгенерировала. | | Снятие маркеров //++agent перед коммитом | Маркеры — часть исходника, дают контекст через месяцы. Снимаются только при следующей крупной правке (см. agent-code-marking). | | Force-push в родительскую ветку | Перезаписывает чужие изменения, ломает blame. | | Коммитить .context/ отдельно от артефактов фазы | Контексты идут в коммите своей фазы — они описывают именно её работу. | | Mерж в main без cross-provider-review PASS | Нарушает gate-протокол orchestrator.md § 7.3. | | Удаление файла из git без явного разрешения пользователя | Потеря работы и аудит-следа. См. § «Запрет на удаление файлов». | | git rm или git rm --cached по инициативе агента | Только пользователь имеет право снимать файлы с трекинга. | | Удаление папки tasks/<TASK-XXX>/ отменённой задачи | Документация задачи — часть аудит-следа. Пометить отменённой, но не удалять. |

Взаимодействие с другими правилами

• agent-code-marking — маркеры внутри коммитов; обязательно для BSL-правок.
• agent-context-protocol — контексты агентов попадают в коммит своей фазы.
• orchestrator.md § 7 — cross-provider-review gate является обязательным условием автомержа.
• protected-paths — файлы в защищённых путях не коммитятся (изменения там вообще запрещены).
• quick-fix.md — простой путь без ветки задачи.

---

depends_on:

• agent-code-marking
• agent-context-protocol
• protected-paths
• framework/skills/framework-meta/quick-fix/SKILL.md
• framework/workflows/full-cycle.md
• framework/workflows/orchestrator.md

---