@rt-tools/agent-kit 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/assets/checks/check-file-size.mjs +19 -4
  2. package/assets/checks/check-state-next.mjs +202 -0
  3. package/assets/checks/check-states.mjs +142 -0
  4. package/assets/checks/check-turn-map.mjs +146 -0
  5. package/assets/checks/rt-kit-checks.config.mjs +16 -2
  6. package/assets/defaults/project.sh +67 -7
  7. package/assets/defaults/turn-map.md +48 -0
  8. package/assets/hooks/browser-device-id.sh +2 -0
  9. package/assets/hooks/browser-guard-device-id.sh +5 -1
  10. package/assets/hooks/browser-guard-no-asking.sh +5 -1
  11. package/assets/hooks/browser-guard-no-listing.sh +2 -0
  12. package/assets/hooks/browser-guard-no-other-drivers.sh +7 -3
  13. package/assets/hooks/browser-guard-require-select.sh +6 -2
  14. package/assets/hooks/claim-guard.sh +5 -1
  15. package/assets/hooks/commit-msg.sh +2 -0
  16. package/assets/hooks/conscience-guard.sh +5 -1
  17. package/assets/hooks/constitution-index.sh +2 -0
  18. package/assets/hooks/dev-server-guard.sh +7 -3
  19. package/assets/hooks/dispatch.sh +69 -0
  20. package/assets/hooks/docs-guard.sh +8 -4
  21. package/assets/hooks/exam-guard.sh +7 -3
  22. package/assets/hooks/git-guard-delivery-signature.sh +2 -0
  23. package/assets/hooks/git-guard-delivery.sh +39 -5
  24. package/assets/hooks/git-guard-main.sh +8 -4
  25. package/assets/hooks/git-guard-push-tests.sh +8 -4
  26. package/assets/hooks/glossary-load.sh +2 -0
  27. package/assets/hooks/grill-gate.sh +6 -2
  28. package/assets/hooks/handoff-entry-guard.sh +6 -2
  29. package/assets/hooks/handoff-write.sh +124 -0
  30. package/assets/hooks/hook-input.sh +54 -0
  31. package/assets/hooks/lint-after-edit.sh +7 -3
  32. package/assets/hooks/observe.sh +2 -0
  33. package/assets/hooks/postmortem-guard.sh +5 -1
  34. package/assets/hooks/proposal-guard.sh +5 -1
  35. package/assets/hooks/prose-style-guard.sh +7 -3
  36. package/assets/hooks/qa-dataid-guard.sh +6 -2
  37. package/assets/hooks/rerun-guard.sh +7 -3
  38. package/assets/hooks/reuse-first-guard.sh +7 -3
  39. package/assets/hooks/roles.sh +2 -0
  40. package/assets/hooks/rule-article.sh +99 -0
  41. package/assets/hooks/skill-gate-layers.sh +2 -0
  42. package/assets/hooks/skill-gate-rearm.sh +5 -1
  43. package/assets/hooks/skill-gate.sh +25 -2
  44. package/assets/hooks/skill-loaded.sh +5 -1
  45. package/assets/hooks/sql-guard-parse.sh +2 -0
  46. package/assets/hooks/sql-guard-request.sh +4 -1
  47. package/assets/hooks/sql-guard-target.sh +2 -0
  48. package/assets/hooks/sql-guard-write.sh +2 -0
  49. package/assets/hooks/sql-guard.sh +6 -2
  50. package/assets/hooks/task-context-load.sh +2 -0
  51. package/assets/hooks/task-flow-guard.sh +8 -4
  52. package/assets/hooks/turn-entry-load.sh +62 -0
  53. package/assets/hooks/turn-exit-guard.sh +44 -17
  54. package/assets/hooks/utf8.sh +35 -0
  55. package/assets/hooks/waiting-turn-guard.sh +5 -1
  56. package/assets/hooks/window-fill-guard.sh +37 -5
  57. package/assets/laws/work-conduct.md +34 -9
  58. package/assets/patterns/dependencies-upgrade.md +1 -1
  59. package/assets/patterns/doc-style-write.md +3 -3
  60. package/assets/patterns/git-workflow-commit.azure.md +2 -202
  61. package/assets/patterns/git-workflow-commit.github.md +2 -258
  62. package/assets/patterns/git-workflow-commit.gitlab.md +1 -217
  63. package/assets/patterns/git-workflow-docker.md +3 -3
  64. package/assets/patterns/git-workflow-merge.md +3 -2
  65. package/assets/patterns/git-workflow-migration.md +3 -3
  66. package/assets/patterns/git-workflow-pr.azure.md +224 -0
  67. package/assets/patterns/git-workflow-pr.github.md +280 -0
  68. package/assets/patterns/git-workflow-pr.gitlab.md +240 -0
  69. package/assets/patterns/git-workflow-restart.md +3 -3
  70. package/assets/patterns/git-workflow-secrets.md +3 -3
  71. package/assets/patterns/task-flow-archive.md +193 -0
  72. package/assets/patterns/task-flow-close.md +11 -160
  73. package/assets/patterns/task-flow-handoff.md +22 -4
  74. package/assets/patterns/task-flow-resume.md +6 -0
  75. package/assets/patterns/task-flow-start.md +41 -0
  76. package/assets/patterns/turn-entry-map.md +81 -0
  77. package/assets/pitfalls/doc-style.md +80 -0
  78. package/assets/pitfalls/git-workflow.azure.md +50 -0
  79. package/assets/pitfalls/git-workflow.github.md +78 -0
  80. package/assets/pitfalls/git-workflow.gitlab.md +49 -0
  81. package/assets/pitfalls/spec-driven.md +36 -0
  82. package/assets/pitfalls/styling-bem.md +45 -0
  83. package/assets/pitfalls/task-flow.md +62 -0
  84. package/assets/pitfalls/testing.md +70 -0
  85. package/assets/rules/deploy-flow.azure.md +106 -0
  86. package/assets/rules/deploy-flow.github.md +113 -0
  87. package/assets/rules/deploy-flow.gitlab.md +108 -0
  88. package/assets/rules/doc-style.md +25 -76
  89. package/assets/rules/git-workflow.azure.md +6 -92
  90. package/assets/rules/git-workflow.github.md +14 -127
  91. package/assets/rules/git-workflow.gitlab.md +6 -93
  92. package/assets/rules/spec-driven.md +39 -30
  93. package/assets/rules/styling-bem.md +20 -39
  94. package/assets/rules/task-flow.md +17 -186
  95. package/assets/rules/testing.md +3 -64
  96. package/assets/rules/turn-conduct.md +206 -0
  97. package/assets/rules/turn-entry.md +93 -0
  98. package/assets/rules/typescript-conventions.md +15 -0
  99. package/assets/skills/agent-kit.md +35 -12
  100. package/assets/templates/pitfalls.md +10 -0
  101. package/assets/templates/rule.md +5 -3
  102. package/lib/assets.d.ts.map +1 -1
  103. package/lib/assets.js +6 -1
  104. package/lib/assets.js.map +1 -1
  105. package/lib/cargo.d.ts +42 -0
  106. package/lib/cargo.d.ts.map +1 -1
  107. package/lib/cargo.js +2 -0
  108. package/lib/cargo.js.map +1 -1
  109. package/lib/cascade.d.ts.map +1 -1
  110. package/lib/cascade.js +19 -1
  111. package/lib/cascade.js.map +1 -1
  112. package/lib/commands.d.ts.map +1 -1
  113. package/lib/commands.js +65 -4
  114. package/lib/commands.js.map +1 -1
  115. package/lib/config.d.ts +16 -1
  116. package/lib/config.d.ts.map +1 -1
  117. package/lib/config.js +8 -0
  118. package/lib/config.js.map +1 -1
  119. package/lib/hooks-map.d.ts +13 -0
  120. package/lib/hooks-map.d.ts.map +1 -1
  121. package/lib/hooks-map.js +33 -1
  122. package/lib/hooks-map.js.map +1 -1
  123. package/lib/observations.d.ts +35 -1
  124. package/lib/observations.d.ts.map +1 -1
  125. package/lib/observations.js +14 -2
  126. package/lib/observations.js.map +1 -1
  127. package/lib/ship.d.ts +2 -0
  128. package/lib/ship.d.ts.map +1 -1
  129. package/lib/ship.js +2 -0
  130. package/lib/ship.js.map +1 -1
  131. package/lib/thresholds.d.ts +49 -0
  132. package/lib/thresholds.d.ts.map +1 -0
  133. package/lib/thresholds.js +151 -0
  134. package/lib/thresholds.js.map +1 -0
  135. package/package.json +1 -1
  136. package/rt-tools-agent-kit-0.12.0.tgz +0 -0
  137. package/assets/commands/agent-kit-digest.md +0 -88
  138. package/assets/commands/rules-review.md +0 -98
  139. package/rt-tools-agent-kit-0.10.0.tgz +0 -0
@@ -2,10 +2,10 @@
2
2
  name: git-workflow-commit
3
3
  kind: pattern
4
4
  rule: git-workflow
5
- description: Паттерн правила git-workflow для дерева в Azure DevOps. Брать на заведение рабочего элемента, ветки, коммит, пуш и создание PR — заведение элемента со всеми шагами, перевод по состояниям, слияние двух задач в одну, сверка очереди работ, работа от учётной записи машинной работы, формат заголовка, привязка PR к элементу, ревьювер, исполнитель и метки, образец тела PR с разделом об оставшемся шаге, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
5
+ description: Паттерн правила git-workflow. Брать на заведение рабочего элемента, ветки, коммит и пуш — заведение элемента с областью и итерацией, перевод состояния, слияние двух задач в одну, работа от учётной записи машинной работы, обход требования документа. Не брать на открытие PR это паттерн git-workflow-pr; не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
6
6
  ---
7
7
 
8
- # Ветка, коммит и PR
8
+ # Задача, ветка и коммит
9
9
 
10
10
  Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
11
11
  `docs/constitution/delivery.md`.
@@ -15,7 +15,6 @@ description: Паттерн правила git-workflow для дерева в A
15
15
  - Заводится рабочий элемент, с которого начинается правка.
16
16
  - Заводится ветка под него.
17
17
  - Готовится коммит или пуш.
18
- - Открывается PR.
19
18
  - Работа перешла на следующий шаг, и элемент переводится в другое состояние.
20
19
 
21
20
  ## Сначала рабочий элемент, потом ветка
@@ -150,212 +149,13 @@ GIT_COMMITTER_NAME="<бот>" GIT_COMMITTER_EMAIL="<почта бота>" \
150
149
  Docs-skip: правка только в тестах хука, зеркала у него нет
151
150
  ```
152
151
 
153
- ## Номер элемента стоит в его заголовке и в заголовке PR
154
-
155
- Форма одна на оба — `[<номер>] <текст>`. Номер стоит в самом заголовке, а не только в теле: в
156
- списке PR тела не видно. Тот же номер несёт и имя ветки, поэтому элемент, ветка и PR читаются
157
- как одно.
158
-
159
- Элемент говорит, что не так; PR тем же номером отчитывается, что сделано:
160
-
161
- ```
162
- элемент [86] Пустой адрес владельца — письма не уходят молча
163
- PR [86] Письмо владельцу с незаполненным адресом попадает в логи
164
- ```
165
-
166
- Инфинитив в заголовок PR не переносится: «исправить» становится «исправлено», «вернуть» —
167
- «возвращено», «добавить» — «добавлено».
168
-
169
- Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
170
- коммита, и там его сверяет `commitlint`.
171
-
172
- ## Не готовое к слиянию открывается черновиком
173
-
174
- Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
175
- PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
176
- черновиком — завершение у черновика хостинг блокирует сам:
177
-
178
- ```bash
179
- AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create --draft true --title '[<КЛЮЧ>-86] …' \
180
- --description "$(cat тело.md)"
181
- ```
182
-
183
- Конвейер проверок у черновика по умолчанию не запускается: молчание прогона за зелёный прогон
184
- не принимается, и набор гоняется на своей машине либо запуском вручную.
185
-
186
- Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
187
- задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
188
- захода.
189
-
190
- Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
191
- решение готово:
192
-
193
- ```bash
194
- AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr update --id 86 --draft false
195
- ```
196
-
197
- До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
198
- черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
199
- ждёт разбора ровно так же, как не снятый.
200
-
201
- ## PR привязывается к элементу при создании
202
-
203
- Привязка задаётся флагом, а не правкой после: у токена может не быть права править чужой
204
- элемент, и вторая команда обойдётся молча, оставив PR ни с чем не связанным.
205
-
206
- ```bash
207
- AZURE_DEVOPS_EXT_PAT="$TOKEN" az repos pr create \
208
- --title '[86] Письмо владельцу с незаполненным адресом попадает в логи' \
209
- --source-branch 86-mail-owner-silence --target-branch main \
210
- --work-items 86 --reviewers <владелец> --delete-source-branch true \
211
- --description 'Закрывает рабочий элемент 86.'
212
- ```
213
-
214
- Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Один PR
215
- закрывает элемент целиком — половину задачи одним PR не выкатывают: у задачи одна ветка, и
216
- работа, которая в неё не влезает, делится на задачи до того, как ветка заводится.
217
-
218
- У уже открытого PR то же ставится правкой:
219
-
220
- ```bash
221
- az repos pr work-item add --id 205 --work-items 86
222
- az repos pr reviewer add --id 205 --reviewers <владелец>
223
- az repos pr update --id 205 --description "$(cat тело.md)"
224
- ```
225
-
226
- Правка описания переписывает его целиком. Тело перечитывается всякий раз, когда в ветку что-то
227
- влилось после публикации: PR утверждает про дерево, а дерево с тех пор изменилось.
228
-
229
- ## Образец тела PR
230
-
231
- Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
232
- оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
233
- заголовок читаются одинаково, а значат разное.
234
-
235
- ```markdown
236
- Закрывает рабочий элемент 86.
237
-
238
- ## Что сделано
239
-
240
- - <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
241
-
242
- ## Чем подтверждено
243
-
244
- - <проверка>: <её вывод одной строкой>
245
- - Не гонялось: <что в набор не вошло и почему>
246
-
247
- ## Оставшийся шаг
248
-
249
- После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
250
- вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
251
- ```
252
-
253
- Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
254
- — в тот ход, которым папка разбирается и снимается черновик:
255
-
256
- ```markdown
257
- ## Оставшийся шаг
258
-
259
- Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
260
- ```
261
-
262
- Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
263
- сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
264
- не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
265
-
266
- Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
267
- заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
268
-
269
- ## Состояние PR читается, а не додумывается
270
-
271
- Команды правки отвечают нулевым кодом и тогда, когда ничего не сделали. Поэтому после них PR
272
- перечитывают:
273
-
274
- ```bash
275
- az repos pr show --id 205 \
276
- --query '{author: createdBy.uniqueName, reviewers: reviewers[].uniqueName, work: workItemRefs[].id}'
277
- ```
278
-
279
- Владельцу называют то, что прочитали, а не то, что заказывали.
280
-
281
- Перечитывают его и по времени, а не только после вызовов, которые молча ничего не сделали:
282
- состояние PR читается перед тем, как что-либо о нём сказать. Между «прогон зелёный» и следующей
283
- фразой владелец успевает влить PR, и всё сказанное о нём после этого — про вчерашний день. Так
284
- владельцу и было предложено влить то, что он влил часом раньше.
285
-
286
- Открытый PR означает, что элемент ждёт разбора, — состояние переставляется тем же движением:
287
-
288
- ```bash
289
- npm run task:move -- 86 in-review
290
- ```
291
-
292
- ## Что проверяется до публикации PR
293
-
294
- Конвейер видит только отправленное, а отправляется оно пушем. Линтеры, юниты и сценарии хуков
295
- снимает гейт пуша — ниже то, чего он не знает.
296
-
297
- 1. **Главная ветка влита в эту ветку** — `git fetch origin && git merge origin/main`.
298
- Всё, что проверяется ниже, проверяется от этого основания: PR с разошедшейся ветки
299
- показывает ревьюверу правку вперемешку с чужой. Порядок и разбор конфликта — паттерн
300
- `git-workflow-merge`.
301
- 2. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
302
- домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
303
- 3. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
304
- целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
305
- 4. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
306
- поведения он не знает — это остаётся за автором.
307
- 5. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`. Какие именно
308
- есть здесь — `implementation.md` правила.
309
- 6. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет.
310
- 7. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
311
- переводится.
312
- 8. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
313
- `browser-verification-measure`.
314
- 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** —
315
- паттерн `seo-verify`.
316
- 10. **PR привязан к рабочему элементу**, ревьювер и исполнитель стоят, а тело собрано по
317
- образцу — разделы «Что сделано», «Чем подтверждено» и «Оставшийся шаг». Раздел оставшегося
318
- шага к этому моменту говорит, что шагов не осталось: черновик снимается после разбора
319
- папки, а не до него.
320
- 11. **Заголовок PR несёт номер элемента и называет работу сделанной:** `[<номер>] <Что
321
- сделано>`, тем же номером, что стоит у элемента и в имени ветки.
322
- 12. **Очередь работ сходится** — `npm run check:board`.
323
- 13. **Состояние PR прочитано, а не выведено из кодов возврата.**
324
- 14. **Набор взят из файла конвейера, а не собран по памяти.** Гейт пуша заведомо уже: он стоит
325
- между командой и пушем, и всё, что дольше секунд, из него вынесено. Что гоняет конвейер,
326
- написано в его файле — этот список и повторяется локально; зелёный гейт полнотой набора не
327
- является.
328
- 15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
329
- теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
330
- снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
331
- PR.
332
-
333
- Сразу после публикации элемент переводится в разбор, и сверка очереди прогоняется ещё раз: до
334
- открытия PR состояние она не судит, а после открытия расхождение видит.
335
-
336
- Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
337
- названное проверенным, ревьювер принимает за проверенное.
338
-
339
- **Раздел «Чем подтверждено» называет и то, что не гонялось.** Список одного прогнанного
340
- неотличим от полного набора, и ревьювер по нему решает, что можно не перепроверять. Цена ошибки
341
- здесь не красный конвейер, а доверие к разделу: однажды прочитанный как полнота, дальше он
342
- перепроверяется весь.
343
-
344
152
  ## Частые промахи
345
153
 
346
154
  - Область и итерация не заданы: элемент заведён, но на доску команды не попал.
347
155
  - Состояние взято не из процесса проекта: перевод отвечает отказом на каждой задаче, и это
348
156
  читается как сломанная команда, а не как неверное имя состояния.
349
- - PR открыт без `--work-items`: связи нет, и по очереди работ не видно, за чем эта правка.
350
- - `AB#<номер>` в коммите принят за привязку PR: он связывает коммит, а очередь читает связь PR.
351
157
  - `git add` с несколькими путями не добавляет ничего, если хоть один путь не существует:
352
158
  команда обрывается на первом промахе целиком. Следующий `git commit --amend` при этом уносит
353
159
  в коммит всё, что осталось в индексе. Состав коммита читается `git show --stat` сразу после
354
160
  него, а не на разборе PR.
355
- - PR открыт без ревьювера: он не попадает во входящие владельца, и очередь стоит, выглядя
356
- работающей.
357
- - `--delete-source-branch` забыт: ветки задач копятся в репозитории, и по списку веток больше
358
- не видно, какая работа идёт сейчас.
359
- - Автозавершение включено до того, как прогнаны проверки до пуша: конвейер зелёный на том, что
360
- он умеет, и слияние происходит без всего остального.
361
161
  - Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.
@@ -2,10 +2,10 @@
2
2
  name: git-workflow-commit
3
3
  kind: pattern
4
4
  rule: git-workflow
5
- description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит, пуш и создание PR — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы и в колонку разбора, слияние двух задач в одну, сверка очереди работ, работа от учётной записи бота, формат заголовка, строка связи с задачей, ревьювер, исполнитель и метки PR, образец тела PR с разделом об оставшемся шаге, чеклист проверок до публикации, обход требования документа. Не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
5
+ description: Паттерн правила git-workflow. Брать на заведение задачи, ветки, коммит и пуш — готовая команда заведения задачи со всеми четырьмя шагами, перевод задачи в колонку работы, слияние двух задач в одну, работа от учётной записи бота, обход требования документа. Не брать на открытие PR это паттерн git-workflow-pr; не брать для миграций и перезапуска прода — это паттерны git-workflow-migration и git-workflow-restart.
6
6
  ---
7
7
 
8
- # Ветка, коммит и PR
8
+ # Задача, ветка и коммит
9
9
 
10
10
  Паттерн правила `git-workflow`. Что при этом должно быть верно — закон
11
11
  `docs/constitution/delivery.md`.
@@ -15,7 +15,6 @@ description: Паттерн правила git-workflow. Брать на зав
15
15
  - Заводится задача, с которой начинается правка.
16
16
  - Заводится ветка под задачу.
17
17
  - Готовится коммит или пуш.
18
- - Открывается PR.
19
18
  - Работа перешла на следующий шаг, и задача переставляется в другую колонку борды.
20
19
 
21
20
  ## Сначала задача на борде, потом ветка
@@ -161,250 +160,6 @@ chore(deploy): docker-compose for vps
161
160
  Docs-skip: правка только в тестах хука, зеркала у него нет
162
161
  ```
163
162
 
164
- ## Номер задачи стоит в её заголовке и в заголовке PR
165
-
166
- Форма одна на оба — `[<КЛЮЧ>-<номер>] <текст>`. Номер стоит в самом заголовке, а не только в
167
- теле: в списке PR тела не видно, а в списке задач номер иначе приходится искать глазами по
168
- колонке слева. Тот же номер несёт и имя ветки — `<КЛЮЧ>-<номер>-<короткий-slug>`, — поэтому
169
- задача, ветка и PR читаются как одно.
170
-
171
- Задача говорит, что не так; PR тем же номером отчитывается, что сделано:
172
-
173
- ```
174
- задача [<КЛЮЧ>-86] Пустой MAIL_OWNER — письма владельцу не уходят молча
175
- PR [<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи
176
-
177
- задача [<КЛЮЧ>-101] Вернуть оверлей загрузки таблицы и включить stylelint гейтом
178
- PR [<КЛЮЧ>-101] Stylelint включён гейтом
179
-
180
- задача [<КЛЮЧ>-212] Сайт не собирается: компонентам кита проставлен префикс приложения вместо своего
181
- PR [<КЛЮЧ>-212] Виджет переписки зовёт кит его собственными именами
182
- ```
183
-
184
- Инфинитив из задачи в заголовок PR не переносится: «исправить» становится «исправлено»,
185
- «вернуть» — «возвращено», «добавить» — «добавлено».
186
-
187
- Номер в заголовке обязан совпасть с номером ветки: гард поставки сверяет их до отправки
188
- команды, а сверка очереди — у каждого открытого PR.
189
-
190
- Тип и область — `fix(site):`, `docs(common):` — в заголовок PR не идут: это формат заголовка
191
- коммита, и там его сверяет `commitlint`. В списке PR он занимает место, ничего не добавляя:
192
- род правки и область уже видны метками.
193
-
194
- ## Не готовое к слиянию открывается черновиком
195
-
196
- Правка кода отдаётся человеку открытым PR: запушенная ветка ему не показывается нигде. Открытый
197
- PR при этом читается как приглашение влить, поэтому у незаконченной работы он открывается
198
- черновиком — кнопку слияния у черновика хостинг блокирует сам:
199
-
200
- ```bash
201
- GH_TOKEN="$TOKEN" gh pr create --draft --title '[<КЛЮЧ>-86] …' --body-file тело.md
202
- ```
203
-
204
- Черновиком идёт всё, что ждёт прогона конвейера, доработки или ответа на вопрос. Вопрос
205
- задаётся в самом PR, а не остаётся в голове исполнителя: человек читает PR, а не переписку
206
- захода.
207
-
208
- Снимается черновик отдельным вызовом, и это тот самый ход, которым исполнитель говорит, что
209
- решение готово:
210
-
211
- ```bash
212
- GH_TOKEN="$TOKEN" gh pr ready 86
213
- ```
214
-
215
- До снятия молчание исполнителя значит «ещё не готово», после — «можно вливать». Снятие
216
- черновика и просьба влить идут одним ходом: снятый черновик, о котором человеку не сказали,
217
- ждёт разбора ровно так же, как не снятый.
218
-
219
- ## PR прикрепляется к задаче
220
-
221
- Тело начинается со строки связи — по ней на борде заполняется поле «Linked pull requests».
222
- Ревьювер, исполнитель и метки задаются той же командой, и PR без них не открывается:
223
-
224
- ```bash
225
- GH_TOKEN="$TOKEN" gh pr create --title '[<КЛЮЧ>-86] Письмо владельцу с незаполненным адресом попадает в логи' \
226
- --reviewer <владелец> --assignee <бот> --label bug --label area:api \
227
- --body 'Closes #86
228
-
229
- …'
230
- ```
231
-
232
- Ревьювер — всегда владелец: без запроса разбора PR не показывается ему в очереди. Исполнитель —
233
- та же учётная запись, от которой идёт машинная работа. Метки берутся у задачи целиком — и род
234
- правки, и все её области; читаются они у задачи, а не выбираются по памяти:
235
-
236
- ```bash
237
- /opt/homebrew/bin/gh issue view 86 --json labels --jq '.labels | map(.name) | join(",")'
238
- ```
239
-
240
- Строка `Closes #<номер>` обязательна: без неё PR не прикрепляется к задаче, и сверка очереди
241
- это находит. Она же и означает, что задача закрывается целиком — половину задачи одним PR не
242
- выкатывают: у задачи одна ветка, и работа, которая в неё не влезает, делится на задачи до
243
- того, как ветка заводится.
244
-
245
- У уже открытого PR то же ставится тремя вызовами REST. `gh pr edit` здесь не годится: он
246
- запрашивает карточки Projects (classic), получает отказ о снятом API и до правки не доходит.
247
-
248
- ```bash
249
- GH=/opt/homebrew/bin/gh
250
- REPO=<владелец>/<репозиторий>
251
-
252
- $GH api -X POST "repos/$REPO/issues/205/labels" -f 'labels[]=bug' -f 'labels[]=area:api'
253
- $GH api -X POST "repos/$REPO/issues/205/assignees" -f 'assignees[]=<бот>'
254
- $GH api -X POST "repos/$REPO/pulls/205/requested_reviewers" -f 'reviewers[]=<владелец>'
255
- ```
256
-
257
- Тем же вызовом правится и само тело: `-f body=` переписывает его целиком, поэтому строка
258
- `Closes #<номер>` пишется заново вместе с остальным текстом.
259
-
260
- ```bash
261
- $GH api -X PATCH "repos/$REPO/pulls/205" -f body="$(cat тело.md)"
262
- ```
263
-
264
- Тело перечитывается всякий раз, когда в ветку что-то влилось после публикации: PR
265
- утверждает про дерево, а дерево с тех пор изменилось.
266
-
267
- ## Образец тела PR
268
-
269
- Четыре раздела, и порядок между ними один: строка связи, что сделано, чем подтверждено,
270
- оставшийся шаг. Раздел, которому нечего сказать, пишется словами — пустой заголовок и снятый
271
- заголовок читаются одинаково, а значат разное.
272
-
273
- ```markdown
274
- Closes #86
275
-
276
- ## Что сделано
277
-
278
- - <правка, названная тем, что она меняет для читателя, а не тем, какие файлы задела>
279
-
280
- ## Чем подтверждено
281
-
282
- - <проверка>: <её вывод одной строкой>
283
- - Не гонялось: <что в набор не вошло и почему>
284
-
285
- ## Оставшийся шаг
286
-
287
- После одобрения ветка получает ещё один коммит — разбор папки задачи, — и только потом
288
- вливается. До этого коммита вливать рано: папка уедет в главную ветку неразобранной.
289
- ```
290
-
291
- Раздел «Оставшийся шаг» стоит последним и переписывается тем же вызовом, что и остальное тело,
292
- — в тот ход, которым папка разбирается и снимается черновик:
293
-
294
- ```markdown
295
- ## Оставшийся шаг
296
-
297
- Не осталось: папка задачи разобрана коммитом `<sha>`, черновик снят. Можно вливать.
298
- ```
299
-
300
- Стоит он там потому, что решение о слиянии принимается на этой странице, а не в переписке:
301
- сказанное владельцу вслух живёт до следующей реплики, а тело лежит у самой кнопки. Одно другого
302
- не отменяет — порядок обоих сообщений владельцу описывает паттерн закрытия работы.
303
-
304
- Проверить тело машиной нечем: ни одна сверка его не читает, а хостинг спрашивает только про
305
- заголовок. Держится образец тем, кто пишет тело, — как и слова вслух.
306
-
307
- ## Состояние PR читается, а не додумывается
308
-
309
- Вызовы, которыми ставятся ревьювер, метки и исполнитель, отвечают нулевым кодом и тогда, когда
310
- ничего не сделали: запрос разбора на автора PR GitHub молча выбрасывает. Поэтому после них PR
311
- перечитывают:
312
-
313
- ```bash
314
- # Ключи латиницей: кириллический ключ без кавычек `jq` не разбирает и падает на нём
315
- $GH api "repos/$REPO/pulls/321" \
316
- --jq '{author: .user.login, reviewers: [.requested_reviewers[].login], labels: [.labels[].name]}'
317
- ```
318
-
319
- Автор здесь — `<бот>`. Если им оказался владелец, ревьювера у PR не будет вовсе:
320
- назначить автора ревьювером нельзя, а отказа на такой запрос не приходит. Владельцу называют
321
- то, что прочитали, а не то, что заказывали.
322
-
323
- Учётная запись, из-под которой пришлось пушить, в этот вызов не переносится: пуш и авторство
324
- PR выбираются отдельно, и `GH_TOKEN` для публикации — всегда токен бота.
325
-
326
- Перечитывают его и по времени, а не только после вызовов, которые молча ничего не сделали:
327
- состояние PR читается перед тем, как что-либо о нём сказать. Между «прогон зелёный» и следующей
328
- фразой владелец успевает влить PR, и всё сказанное о нём после этого — про вчерашний день. Так
329
- владельцу и было предложено влить то, что он влил часом раньше.
330
-
331
- Открытый PR означает, что задача ждёт разбора, — колонка переставляется тем же движением:
332
-
333
- ```bash
334
- npm run task:move -- 86 in-review
335
- ```
336
-
337
- Голым GraphQL по идентификаторам проекта, элемента и варианта поля это не пишется: команда
338
- знает их сама, а собранный по памяти запрос молча ставит не ту колонку — отказа у борды на
339
- это нет.
340
-
341
- ## Что проверяется до публикации PR
342
-
343
- Проверок на самом PR нет: выкатка запускается пушем в главную ветку, и до мержа никто не
344
- гоняет ничего. Линтеры, юниты и сценарии хуков снимает гейт пуша — ниже то, чего он не знает.
345
-
346
- 1. **Главная ветка влита в эту ветку** — `git fetch origin && git merge origin/main`.
347
- Свежесть основания между ветками одного захода не наследуется: вторая и третья ветка
348
- отводятся после своего `fetch`, а не от ссылки, подтянутой под первую. Пока идёт работа,
349
- главная уходит вперёд — чаще всего собственным PR того же исполнителя, влитым час
350
- назад.
351
- Всё, что проверяется ниже, проверяется от этого основания: PR с разошедшейся ветки
352
- показывает ревьюверу правку вперемешку с чужой. Порядок и разбор конфликта — паттерн
353
- `git-workflow-merge`.
354
- 2. **В ветке только та правка, за которой её заводили** — `git diff main...HEAD --stat`. Чужой
355
- домен в списке файлов означает, что правка расползлась, и её надо вернуть в свои границы.
356
- 3. **Ни мока, ни подменённого ответа, ни отладочной строки** — `git diff main...HEAD` читается
357
- целиком, а не по именам файлов. На прод они уезжают молча и портят настоящие данные.
358
- 4. **Документ едет тем же коммитом.** Пару называет `docs-guard`, но спек домена и правку его
359
- поведения он не знает — это остаётся за автором.
360
- 5. **Проверки текстов и раскладки зелёные** — те, что дерево завело в `tools/`: сверка
361
- сценариев с тестами, путей в документах, раскладки либ, повторов и классов без правила.
362
- Какие именно есть здесь — `implementation.md` правила.
363
- 6. **Все приложения дерева собираются** — `nx build` по каждому. Гейт пуша сборку не гоняет:
364
- она длиннее всего, что он успевает сделать между командой и пушем.
365
- 7. **Видимый текст заведён во всех локалях перевода** — тестом полноты словарей, если дерево
366
- переводится.
367
- 8. **Правка вёрстки подтверждена замером**, а не взглядом, и снята при узком экране — паттерн
368
- `browser-verification-measure`.
369
- 9. **Правка разметки публичного сайта проверена на прод-сборке по всем локалям перевода** — паттерн
370
- `seo-verify`.
371
- 10. **Тело PR собрано по образцу** — начинается строкой `Closes #<номер>`, несёт разделы «Что
372
- сделано», «Чем подтверждено» и «Оставшийся шаг», а метки, ревьювер и исполнитель стоят.
373
- Раздел оставшегося шага к этому моменту говорит, что шагов не осталось: черновик снимается
374
- после разбора папки, а не до него.
375
- 11. **Заголовок PR несёт номер задачи и называет её сделанной:** `[<КЛЮЧ>-<номер>] <Что сделано>`,
376
- тем же номером, что стоит у задачи и в имени ветки. Инфинитив из задачи в него не
377
- переносится, тип и область коммита — тоже.
378
- 12. **Очередь работ сходится** — `npm run check:board`. Задача на борде, с исполнителем и
379
- номером в заголовке; PR один на задачу, и закрывает он её целиком.
380
- 13. **Состояние PR прочитано, а не выведено из кодов возврата** — автор `<бот>`,
381
- ревьювер — владелец, метки те же, что у задачи. Владельцу называют прочитанное.
382
- 14. **Набор взят из файла конвейера, а не собран по памяти.** Гейт пуша заведомо уже: он стоит
383
- между командой и пушем, и всё, что дольше секунд, из него вынесено. Что гоняет конвейер,
384
- написано в его файле — этот список и повторяется локально; зелёный гейт полнотой набора не
385
- является.
386
- 15. **Набор пересмотрен после вливания главной ветки.** Он выбирается по тому, что ветка везёт
387
- теперь, а не по тому, что правил автор. Ветка, не тронувшая ни строки показа, прогоняет
388
- снимки витрин: с момента вливания их гоняет конвейер на её коде, и красное придёт на её
389
- PR.
390
-
391
- Список этот — про снятие черновика, а не про его открытие. Черновиком PR открывается раньше:
392
- пока работа идёт, человеку показывают то, что уже есть, вместе с тем, чего ещё нет. Пункты 1–15
393
- проходятся перед `gh pr ready`, и невыполненный пункт означает, что черновик не снимается, — а
394
- не то, что PR не открывается.
395
-
396
- Сразу после публикации задача переставляется в разбор — `npm run task:move -- <номер>
397
- in-review`, — и `npm run check:board` прогоняется ещё раз: до открытия PR колонку он не судит,
398
- а после открытия расхождение видит.
399
-
400
- Сделанное рассуждением и сделанное замером в теле PR разводятся прямо: непроверенное,
401
- названное проверенным, ревьювер принимает за проверенное.
402
-
403
- **Раздел «Чем подтверждено» называет и то, что не гонялось.** Список одного прогнанного
404
- неотличим от полного набора, и ревьювер по нему решает, что можно не перепроверять. Цена ошибки
405
- здесь не красный конвейер, а доверие к разделу: однажды прочитанный как полнота, дальше он
406
- перепроверяется весь.
407
-
408
163
  ## Частые промахи
409
164
 
410
165
  - `gh` в оболочке пользователя подменён — звать `/opt/homebrew/bin/gh` напрямую.
@@ -431,15 +186,4 @@ in-review`, — и `npm run check:board` прогоняется ещё раз:
431
186
  ловит и сверка — ей ветка тоже не видна.
432
187
  - `gh api graphql --paginate` на запросе элементов борды уходит в повтор первой страницы:
433
188
  курсор берётся из ответа руками, а полнота сверяется с `items(first: 1) { totalCount }`.
434
- - Второй строкой `Closes` в одном PR задача больше не закрывается: две задачи в одной ветке
435
- откатываются только вместе. Либо это одна задача — и вторая поглощается, — либо две ветки.
436
- - Половина задачи, уехавшая своим PR, тоже промах: тело такого PR начинается со слов «Часть
437
- #<номер>» вместо `Closes`, задача остаётся открытой, и после отката видно её целой. Работа,
438
- которая в одну ветку не влезает, делится на задачи до того, как ветка заводится.
439
- - PR открыт без ревьювера: он не попадает во входящие владельца вовсе, и очередь стоит,
440
- выглядя работающей. Так шестнадцать PR ждали разбора, которого никто не запрашивал.
441
- - Метки поставлены по названию PR, а не прочитаны у задачи: область теряется, и по борде не
442
- видно, что правка задела ещё и сайт.
443
- - Задача закрыта не полностью, а метки перенесены целиком: тикет остаётся открытым, и это
444
- говорится в теле PR, а не подразумевается строкой `Closes`.
445
189
  - Правка владельца ни токена, ни переменных не берёт — они только для машинной работы.