@rt-tools/agent-kit 0.11.0 → 0.13.0

package/assets/patterns/task-flow-archive.md

@@ -0,0 +1,195 @@
+---
+name: task-flow-archive
+kind: pattern
+rule: task-flow
+description: Паттерн правила task-flow. Брать, когда тексты приведены и папка задачи разбирается последним коммитом до открытия заявки: переезд в описание прошлого, сверка очереди работ, разбор закрытой работы правилами и то, что делать с его находками. Не брать для вливания договорённости, открытия заявки и снятия черновика — это паттерн task-flow-close.
+---
+
+# Разбор папки задачи и разбор работы правилами
+
+Паттерн правила `task-flow`. Что при этом должно быть верно — закон
+`docs/constitution/work-conduct.md`. Что делается до этого — снятие черновика, вливание
+договорённости и приведение текстов — паттерн `task-flow-close`.
+
+## Когда брать
+
+- Договорённость влита, тексты домена приведены, и папка задачи разбирается последним
+  коммитом ветки — до открытия заявки, а не после одобрения.
+- Работа слита человеком, и её разбирают правилами.
+- Разбор вернул находки, и их надо куда-то положить.
+
+## Состояние `разбор-кончился`: папка задачи разбирается
+
+Разбор идёт по трём исходам, а не по двум.
+
+**Первым отбирается действующее требование.** Всё, что останется верным и завтра, становится
+статьёй закона, пунктом правила или разделом паттерна — по тому, о чём оно говорит. Признак
+отбора один и записан здесь заранее: перестанет ли текст быть верным, если завтра всё
+переделать. Перестанет — это рассказ о состоявшемся; не перестанет — требование, и место ему в
+слое правил. Закон при этом в ветке не правится — его статья приносится владельцу текстом.
+
+**Вторым отбирается рассказ о состоявшемся переезде.** Он уезжает в описание прошлого и
+называет для каждого перенесённого решения, куда оно ушло: иначе решение, ставшее правилом, и
+решение, потерянное при переносе, выглядят одинаково — записью, на которую никто не ссылается.
+
+**Третьим удаляется остальное.**
+
+Порядок именно такой: начав с переезда, исполнитель увозит вместе с ним и действующее — под
+конец работы это дешевле, чем разбирать.
+
+Целиком в архив не переносится: `docs/archive/` — место для записей о состоявшемся, которые
+кто-то читает, а не свалка ходов работы. Таблица ниже говорит о том, что осталось после
+первого отбора.
+
+| Файл            | Куда                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `grill.md`      | в `docs/archive/` — ответы владельца невосстановимы, и это единственная запись о том, почему задача поставлена так |
+| `progress.md`   | в `docs/archive/`, если в нём есть решения по ходу с причинами; иначе удаляется                                    |
+| `plan.md`       | удаляется — после выкатки на его вопрос отвечает код, а на «как работает» отвечает спек домена                     |
+| находки разбора | переезжают к замыслу эпика — их читает владелец, когда эпик кончится; работа вне эпика показывает их сразу         |
+
+Уезжающее складывается одним файлом с говорящим именем, а не папкой из трёх:
+
+```bash
+cat docs/tasks/<КЛЮЧ>-<номер>-<slug>/grill.md > docs/archive/<ЧТО_РЕШАЛИ>.md
+rm -r docs/tasks/<КЛЮЧ>-<номер>-<slug>
+```
+
+Разбор идёт последним коммитом ветки, до открытия заявки: открытие с лежащей папкой отбивает
+гард поставки. Прежде уборка стояла после одобрения — считалось, что замысел нужен на диске всё
+время разбора. Но кнопку слияния нажимает человек на хостинге, куда гард не достаёт, и вливает
+он, как только видит зелёное: трижды подряд папка уехала в главную неразобранной. Замысла после
+уборки на диске нет намеренно, и правку по замечаниям гард хода работы пропускает по признаку
+из истории ветки.
+
+### Работа, разбирающая чужую папку, разбирает две
+
+Своя папка у такой работы есть — она заводится наравне со всеми, исключения из этого нет. Обе
+снимаются последним коммитом, и порядок между ними один: сперва чужая, потом своя. Начав со
+своей, исполнитель теряет замысел на диске, а он ещё нужен — гард отбивает правку без него, а
+правка по замечаниям разбора идёт в ту же ветку.
+
+```bash
+cat docs/tasks/<чужая>/grill.md > docs/archive/<ЧТО_РЕШАЛИ_ТАМ>.md
+rm -r docs/tasks/<чужая>
+cat docs/tasks/<своя>/grill.md > docs/archive/<ЧТО_РЕШАЛИ_ЗДЕСЬ>.md
+rm -r docs/tasks/<своя>
+```
+
+Две записи в архиве, а не одна: работы разные, и решения в них разные. Сверка очереди работ
+после этого не называет ни одной папки — этим и проверяется, что разобраны обе.
+
+**Следующее движение:** разобранная папка уезжает в ветку тем же коммитом, следом сверяется
+очередь работ, и тем же ходом открывается заявка — паттерн `task-flow-close`.
+
+## Состояние `папка-разобрана`: сверка очереди работ
+
+```bash
+npm run check:board   # папка закрытой задачи среди текущих, брошенные черновики
+npm run check:specs   # договорённость влита, привязки на месте
+npm run check:docs    # пути, названные в текстах, существуют
+```
+
+**Следующее движение:** расхождения, названные сверками, чинятся тем же ходом; чинить нечего —
+тот же ход открывает заявку черновиком и называет владельцу номер, паттерн `task-flow-close`.
+
+## Состояние `влито`: работа разбирается правилами — фоном, следом за PR
+
+Шаг о слое правил, а не о продукте: что за эту работу грузилось, что помогло, чего не хватило и
+где текст правила разошёлся с деревом. Знает это только тот заход, который работу вёл, — через
+сутки не знает никто.
+
+Ведёт разбор роль разбора закрытой задачи, если дерево её разложило; не разложившее ведёт его
+само, теми же вопросами. Файлов роль не правит — приносит готовые формулировки, а вставлять их
+решает владелец.
+
+**Запускается разбор в фоне, сразу за открытием PR, и ход на нём не кончается.** Роль ничего не
+спрашивает, пока работает, и быстрее от ожидания не идёт: следующая задача берётся тем же ходом,
+которым запущен разбор.
+
+Порядок один и переставлять его нельзя:
+
+1. **Сводка собирается до запуска** — пока задача ещё в голове. Что делали, что пошло не так,
+   что грузилось и что каждое правило дало, на какие грабли окружения наткнулись. Собранная
+   через две задачи, она пересказывает историю ветки вместо того, что было на самом деле.
+2. **Роль уходит в фон** — инструментом запуска роли, с путём к списку загруженного и сводкой
+   целиком. Ход продолжается следующей задачей.
+3. **Вернувшиеся находки принимают одним ходом** — записать и вернуться к прежнему. Разбор,
+   отложенный «до удобного момента», не случается вовсе: заход кончается раньше.
+
+**Следующее движение:** пока роль разбирает, тот же ход занят следующей задачей; вернувшиеся
+находки принимаются одним ходом — записать и продолжить прежнее.
+
+## Состояние `влито`: находки разбора ложатся в папку задачи и ждут владельца
+
+Ответ роли живёт в переписке и умирает вместе с ней, поэтому он сразу ложится на диск — в папку
+задачи, файлом рядом с ходом работы. Пишет его исполнитель: роль файлов не пишет.
+
+Папка задачи умирает со слиянием, а находки должны пережить весь эпик — владелец читает их
+разом, когда эпик кончился. Поэтому при разборе папки файл находок не удаляется вместе
+с остальным, а **переезжает к замыслу эпика**: там его найдут и после того, как ветка въехала.
+Работа вне эпика показывает находки владельцу сразу, тем же ходом.
+
+**Наружу без слова владельца уезжает только сводка наблюдений.** Она говорит, чем пользовались
+и чем не пользовались ни разу, — это факт, и мнением он не станет. Предложение — другое дело:
+это заготовка правки чужого дерева, и часть заготовок отпадает при первом же чтении. Уехавшая
+без разбора, она становится работой того, кто её не заказывал.
+
+Порядок такой: находки копятся у замысла эпика → эпик кончился → владелец читает их разом и
+говорит, что из них верно → названное им оформляется предложением и уезжает. Чем отправляют —
+скил слоя правил, если дерево его разложило.
+
+У каждой находки называется адрес, и адресов три:
+
+| Куда                       | Что туда идёт                                                            |
+| -------------------------- | ------------------------------------------------------------------------ |
+| слой правил — предложением | то, что верно любому дереву этого класса: статья, пункт правила, паттерн |
+| имена этого дерева         | то, что верно здесь: компаньон правила, профиль, карта гейта             |
+| надстройка над разложенным | то, что здесь звучит иначе, чем в пакете                                 |
+
+Без адреса правка ложится туда, где её видит автор, — то есть в своё дерево, — и общее оседает
+в одном месте, оставаясь неизвестным всем остальным.
+
+**Разбор без правки закрытым не считается.** Из него выходит либо правка слоя правил, либо
+предложение наружу; не вышло ни того ни другого — это жалоба, и она повторится. Предложение, о
+котором владелец сказал вслух, уходит наружу в тот же ход: написанное и не отправленное лежит в
+дереве неотличимо от отправленного.
+
+**Следующее движение:** записанные находки работу не держат — следующая задача уже идёт, а
+владельцу о них говорится, когда кончился эпик.
+
+## Ловушки
+
+- **Папку разбирают до открытия заявки — потом о ней уже никто не вспомнит.** Сверка очереди
+  считает задачу закрытой по слиянию: после него за папку никто не отвечает — работа перешла к
+  следующей задаче, и находка достанется чужому заходу. Три раза подряд папка закрытой задачи
+  так и уехала в главную ветку, в последний раз их набралось пять. Держит это гард поставки:
+  открытие заявки отбивается, пока папка лежит в ветке.
+- **Разбор папки идёт последним коммитом, после того как гейт пуша прошёл целиком.** Порядок
+  один: мерж главной ветки, все линтеры и проверки зелёные, вливание договорённости, приведение
+  текстов домена, разбор папки — и только потом заявка.
+- **После разбора замысла на диске нет, и собирать папку заново не надо.** Правку по замечаниям
+  разбора и починку красного прогона гард хода работы пропускает по признаку из истории ветки:
+  папка, снятая её коммитом, и есть признак отданной работы. Собранная заново папка вернула бы
+  отказ гарда поставки на следующем же вызове.
+- **Если папку просто удалить, первым пропадёт `grill.md`.** Удалить проще, чем разобрать, а
+  слова владельца записаны только там, и восстановить их неоткуда. Поэтому гард требует, чтобы
+  ветка добавила запись в архив. Что именно перенесли, он не проверяет — это смотрит владелец
+  на ревью.
+- **Шаги закрытия с владельцем не согласуются — они перечислены здесь.** Разбор работы
+  правилами входит в закрытие так же, как вливание договорённости и разбор папки; владелец
+  решает не то, запускать ли его, а что делать с находками. Ход, кончившийся таким вопросом,
+  отбивает гард разговора: за ход правила не читались, а ответ стоит в них. Спрашивается только
+  то, чего в правилах нет.
+- **Блок готового кода в паттерне стареет от чужой правки.** Он не привязан ни к чему: сверка
+  спеков читает утверждения правила, а пример под ними не читает вовсе. Два поля, ставших
+  обязательными в чужой работе, сделали пример в соседнем паттерне несобираемым — сам он при
+  этом не изменился ни на знак и в след задачи не попал, потому что ни одного слова той работы
+  в нём нет. Паттерн находится по имени правленого символа, а не по теме работы.
+- **Замысел эпика правят только там, где вписывают «чем кончился».** Границы эпика и
+  порядок задач в нём при этом остаются прежними, а работа их уже нарушила: задача, решившая
+  читать спеки, оставила над собой границу «спеки — вторая очередь», и следующий исполнитель
+  прочитает её как действующую. Границы эпика перечитываются целиком тем же заходом, что и
+  итог работы.
+- **Архив не обновляется после выкатки.** Уехавшее туда описывает день переезда, и правится
+  оно только вместе с признанием, что описывало неверно.