docs(workflow): align branch and release instructions

AGENTS.md

@@ -40,6 +40,7 @@ bin/
 docs/
   git-workflow/              # Документация, копируемая в проект-потребитель
     index.md                 # Оглавление раздела
+    glossary.md              # Словарь терминов со ссылками на определения
     branches.md              # Ветки: типы, именование, жизненный цикл
     commits.md               # Conventional Commits: формат и правила
     pull-request.md          # Процесс PR и требования
@@ -50,7 +51,8 @@ docs/
     releases/                # Описание артефактов релиза
       index.md
     templates/
-      release-plan.template.md  # Шаблон плана релиза
+      release-plan.template.md         # Шаблон плана обычного релиза
+      hotfix-release-plan.template.md  # Шаблон плана срочного исправления
 todo/                        # Внутренние задачи по доработке пакета
 ```
 

README.md

@@ -10,6 +10,7 @@
 
 ## Правила
 
+- **[Словарь терминов](docs/git-workflow/glossary.md)** — короткие определения со ссылками на отдельные термины
 - **Ветки** — как назвать ветку для задачи, релиза или хотфикса; когда удалить
 - **Коммиты** — Conventional Commits: тип, scope, subject — чтобы история читалась как журнал изменений
 - **Пулреквесты** — от создания до мержа: проверки, ревью, squash

docs/git-workflow/branches.md

@@ -15,92 +15,187 @@ package: prikotov/git-workflow
 
 ## Целевая модель
 
-- `master` — integration branch для обычной разработки.
+- Основная ветка — ветка по умолчанию репозитория и источник обычных релизов; на неё указывает `origin/HEAD`.
 - `task/<short-description>` — рабочая ветка для feature, bugfix, docs и рефакторинга.
-- `release/x.y` — активная линия стабилизации релиза.
+- `release/x.y.z` — отдельная ветка каждого выпуска, включая каждый патч.
 - `hotfix/x.y.z-<short-description>` — срочный patch для уже выкаченного production release.
 - Production состояние фиксируется **tag** `vX.Y.Z`, а не текущим состоянием ветки.
-- Одновременно поддерживается только одна активная `release/x.y`.
+- Одновременно готовь один обычный релиз; срочное исправление может готовиться параллельно. Сохраняй ветки всех выпусков.
 
 ## Общие правила
 
-- Запрещены прямые правки в `master`.
-- Запрещены прямые правки в `release/*`.
+- Вноси изменения в основную ветку только через PR.
+- Работай и коммить в `task/*`, `release/*` и `hotfix/*` по запросу пользователя. До срочного выпуска изменяй его `release/x.y.z` только через PR из `hotfix/*`.
 - Запрещён деплой в production из текущего состояния ветки.
 - Одна ветка — одна цель: не смешиваем разные задачи и “случайные” улучшения.
 - Массовые перемещения и переименования файлов не смешиваем с последующим рефакторингом и изменением поведения.
 - Перед стартом убедись, что рабочее дерево чистое: `git status`.
 - Если есть чужие незакоммиченные изменения — остановись и уточни у пользователя.
+- Для синхронизации веток используй только слияние (merge), без переписывания существующих коммитов.
+- Изменения после одобрения требуют повторных проверок и нового одобрения по [правилам PR](pull-request.md#подготовка-pr).
 
-## Именование
+## Работа с ветками
 
-- `task/<short-description>` — английский, `kebab-case`, кратко по смыслу.
-- `release/x.y` — release line по `major.minor`.
-- `hotfix/x.y.z-<short-description>` — patch version плюс короткое описание.
+### Task branch
 
-Примеры:
-- `task/docs-release-workflow`
-- `release/0.9`
-- `hotfix/0.9.3-login-timeout`
+Используется для обычной разработки и документации.
 
-## Откуда создавать ветки
+#### Именование
 
-### Task branch
+`task/<short-description>` — короткое описание на английском в `kebab-case`.
 
-Используется для обычной разработки и документации.
+Пример: `task/docs-release-workflow`.
+
+#### Создание
+
+Для обычных задач база и цель PR — основная ветка. Документы будущего релиза можно дополнять в этих же задачах.
 
 ```bash
-git switch master
-git pull origin master
+git fetch origin &&
+# Обновить локальный указатель основной ветки по данным origin.
+git remote set-head origin --auto &&
+# Получить её имя, например origin/main.
+base=$(git symbolic-ref --short refs/remotes/origin/HEAD) &&
+# Убрать префикс origin/ и переключиться на локальную ветку.
+git switch "${base#origin/}" &&
+git pull --ff-only origin "${base#origin/}" &&
 git switch -c task/<short-description>
 ```
 
+#### Синхронизация
+
+Синхронизируй `task/*` с основной веткой до окончательного одобрения PR. Находясь в ветке задачи, получи актуальное состояние основной ветки:
+
+```bash
+git fetch origin &&
+# Обновить локальный указатель основной ветки по данным origin.
+git remote set-head origin --auto
+```
+
+Затем выполни слияние:
+
+```bash
+git merge origin/HEAD
+```
+
+#### Завершение
+
+Удали `task/*` локально и в `origin` после слияния PR.
+
 ### Release branch
 
-Создаётся только после решения, что конкретный набор изменений идёт в production.
+Используется для подготовки обычного релиза.
+
+#### Именование
+
+`release/x.y.z` — полный номер выпуска по `major.minor.patch`.
+
+Пример: `release/0.9.3`.
+
+#### Создание
+
+Для нового выпуска имя ветки и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их. В имени `release/x.y.z` укажи полную версию нового выпуска.
+
+Для обычного релиза создай ветку от актуальной основной: [процесс релиза](release.md#1-финализация-в-релизной-ветке).
+
+```bash
+git fetch origin &&
+  # Обновить локальный указатель основной ветки по данным origin.
+  git remote set-head origin --auto &&
+  # Получить её имя, например origin/main.
+  base=$(git symbolic-ref --short refs/remotes/origin/HEAD) &&
+  # Убрать префикс origin/ и переключиться на локальную ветку.
+  git switch "${base#origin/}" &&
+  git pull --ff-only origin "${base#origin/}" &&
+  git switch -c release/x.y.z &&
+  git push -u origin release/x.y.z
+```
+
+Правила для ветки обычного релиза:
+- коммить исправления, версии и релизные документы в этой ветке;
+- направляй PR из неё в основную ветку; слей PR до публикации тега;
+- продолжай подготовку того же выпуска в существующей ветке; для следующего выпуска создай новую, не переиспользуй старую.
+
+#### Синхронизация
+
+Синхронизируй `release/x.y.z` с основной веткой до окончательного одобрения PR. Находясь в релизной ветке, получи актуальное состояние основной ветки:
+
+```bash
+git fetch origin &&
+# Обновить локальный указатель основной ветки по данным origin.
+git remote set-head origin --auto
+```
+
+Затем выполни слияние:
 
 ```bash
-git switch master
-git pull origin master
-git switch -c release/x.y
-git push -u origin release/x.y
+git merge origin/HEAD
 ```
 
-Правила для `release/x.y`:
-- в неё попадают только stabilizing changes;
-- новые feature PR продолжают идти в `master`;
-- после выпуска patch changes из release line не должны теряться в `master`.
+#### Завершение
+
+- Сохраняй `release/x.y.z` и тег выпуска локально и в `origin`.
+- Не удаляй релизную ветку при слиянии PR и не переиспользуй для другой версии.
+- Отменённого кандидата не тегируй.
 
 ### Hotfix branch
 
-По умолчанию hotfix создаётся от **текущего production tag** `vX.Y.Z`, а не от `master`.
+Используется для срочного исправления ошибки в рабочей версии без нарушения совместимости.
+
+#### Именование
+
+`hotfix/x.y.z-<short-description>` — версия нового патч-релиза и короткое описание на английском в `kebab-case`.
+
+Пример: `hotfix/0.9.3-login-timeout`.
+
+#### Создание
+
+Для нового выпуска имена веток и тег новой версии должны быть свободны локально и в `origin`; при конфликте остановись, не перезаписывай их.
+
+Сначала создай целевую `release/x.y.z` нового выпуска от текущего рабочего тега `vX.Y.Z`. Например: от `v1.2.0` — новую `release/1.2.1`, не меняя `release/1.2.0`.
+
+```bash
+git fetch origin --tags --prune &&
+  git switch -c release/x.y.z vX.Y.Z &&
+  git push -u origin release/x.y.z
+```
+
+Затем создай ветку срочного исправления от **тега текущей версии в рабочей среде** `vX.Y.Z`, не от вершины сохранённой релизной ветки. В имени `hotfix/x.y.z-<short-description>` укажи версию нового выпуска.
 
 ```bash
-git fetch origin --tags --prune
+git fetch origin --tags --prune &&
 git switch -c hotfix/x.y.z-<short-description> vX.Y.Z
 ```
 
-Если активная `release/x.y` уже соответствует текущей production line, hotfix всё равно стартует от production tag, а затем вливается в `release/x.y` и обратно в `master`.
+Подготовь исправление и файлы патч-релиза в этой ветке. Слей PR из неё в `release/x.y.z` нового выпуска до создания нового тега по [сценарию срочного исправления](release.md#hotfix-и-patch-release).
+
+#### Синхронизация
 
-## Синхронизация
+Синхронизируй `hotfix/*` только с целевой `release/x.y.z` нового выпуска до окончательного одобрения PR. До публикации GitHub Release не подтягивай основную ветку ни в `hotfix/*`, ни в целевую `release/x.y.z`; изменения в целевую ветку принимай только через PR из `hotfix/*`.
 
-- `task/*` синхронизируется с `master`.
-- `release/*` синхронизируется только с собственной release line; новые feature commits из `master` туда не подтягиваются автоматически.
-- `hotfix/*` после merge должен присутствовать в active `release/x.y` и в `master`.
-- Если не уверен, использовать `merge` или `rebase`, — уточни у пользователя.
+Находясь в ветке срочного исправления, замени `x.y.z` версией нового выпуска и выполни слияние:
 
 ```bash
-git fetch origin
-git merge origin/master
+git fetch origin &&
+git merge origin/release/x.y.z
 ```
 
+#### Возврат в основную ветку
+
+После публикации GitHub Release открой PR из этой `release/x.y.z` в основную ветку. Если нужна адаптация к основной ветке, выполни её в `release/x.y.z`, не в `hotfix/*`:
+
 ```bash
-git fetch origin
-git rebase origin/master
+git fetch origin &&
+# Обновить локальный указатель основной ветки по данным origin.
+git remote set-head origin --auto &&
+git switch release/x.y.z &&
+git merge origin/HEAD
 ```
 
-## Завершение
+После адаптации повтори проверки и получи одобрение PR. Не меняй опубликованный тег.
+
+#### Завершение
 
-- После merge PR рабочую ветку нужно удалить локально и в `origin`.
-- После выпуска `release/x.y`, когда line закрыта и merge-back завершён, release branch можно удалить.
-- Hotfix branch удаляется сразу после merge-back в целевые ветки.
+- Удали `hotfix/*` локально и в `origin` после публикации GitHub Release и слияния исправления в основную ветку.
+- Сохраняй целевую `release/x.y.z` и тег выпуска локально и в `origin`; не удаляй ветку при слиянии PR и не переиспользуй для другой версии.
+- Отменённого кандидата не тегируй.

docs/git-workflow/code-review.md

@@ -25,7 +25,7 @@ package: prikotov/git-workflow
 - Зафиксируй ожидаемый результат и критерии приёмки.
 - Проверь PR по правилам: [Pull Request (PR)](pull-request.md).
 - Несоответствия правилам PR — это `blocking`.
-- Проверь результаты проверок (CI или `make check`).
+- Проверь результаты проверок проекта, включая CI.
 - Прочитай diff целиком.
 - Если правила нет или оно неоднозначно — зафиксируй это и предложи отдельную задачу на уточнение конвенций проекта.
 - Проверяй только в рамках задачи и заявленных границ PR.

docs/git-workflow/commits.md

@@ -80,7 +80,7 @@ Scope указывает на область изменения, в качест
 - Не смешивай в одном коммите разные типы изменений.
 - Не смешивай в одном коммите поведение и форматирование.
 - Не смешивай `move/rename` и `refactor/behavior change` в одном коммите.
-- Используй `git commit -m ...` без генераторов.
+- Используй `git commit -m ...` без генераторов, в том числе для релизных коммитов.
 
 ## Примеры
 
@@ -156,13 +156,11 @@ vendor/bin/validate-commit .git/COMMIT_EDITMSG
 | `1` | Сообщение невалидно |
 | `2` | Ошибка конфига или выполнения |
 
-### Обход валидации (только для экстренных случаев)
+### Исключения для валидации
 
-```bash
-git commit --no-verify -m "your commit message"
-```
-
-⚠️ Используйте `--no-verify` только в исключительных случаях!
+- Обход хуков через `--no-verify` запрещён без явного исключения в политике проекта-потребителя.
+- Исключение должно определять условия обхода и необходимые замещающие проверки; укажи основание и результаты в PR.
+- Формат сообщения сохраняется при любом исключении.
 
 ### CI
 
@@ -177,7 +175,7 @@ vendor/bin/validate-commit <(git log -1 --format=%B)
 
 1. Выбери `<type>`.
 2. Выбери `<scope>`.
-3. Сформулируй `<subject>`.
+3. Сформулируй `<subject>`: `английский текст / русский текст`.
 4. Создай коммит: `git commit -m "<type>(<scope>): <subject>"`.
 
 ## Дополнительные ресурсы