@rt-tools/agent-kit 0.3.0 → 0.5.0

package/assets/hooks/task-context-load.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# rt-hook: SessionStart startup|resume|compact|clear
+# SessionStart: состояние незаконченной работы уезжает в контекст на каждом запуске сессии.
+#
+# Памятью это не держится по той же причине, что и словарь: замысел читают перед правкой
+# файла, а разговор с владельцем начинается с вопроса — и заход отвечает, не зная, что работа
+# уже наполовину сделана. Здесь замысел и ход работы приходят до первой реплики, и владельцу
+# не приходится пересказывать то, что уже записано.
+#
+# Разбор просьбы (`grill.md`) отдаётся путём, а не текстом: он неизменен, объёмен и нужен
+# реже остальных.
+#
+# FAIL-OPEN: нет `jq`, не git-репозиторий, нет папки задачи — выходим молча. Сессия важнее
+# контекста.
+
+ROOT="${CLAUDE_PROJECT_DIR:-.}"
+command -v jq >/dev/null 2>&1 || exit 0
+cd "$ROOT" 2>/dev/null || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+branch="$(git branch --show-current 2>/dev/null)"
+[ -z "$branch" ] && exit 0
+
+# Профиль дерева: сперва умолчание пакета, поверх него — надстройка проекта, если она есть.
+rt_hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for profile in "$rt_hooks_dir/../rt-kit/defaults/project.sh" "$rt_hooks_dir/../defaults/project.sh" "$ROOT/.claude/rt-kit/defaults/project.sh" "$ROOT/.claude/rt-kit/project.sh"; do
+    # shellcheck disable=SC1090
+    [ -f "$profile" ] && . "$profile" 2>/dev/null
+done
+
+TASKS_DIR="${RT_TASKS_DIR:-docs/tasks}"
+[ -z "$TASKS_DIR" ] && exit 0
+
+DIR="$TASKS_DIR/$branch"
+PLAN="$DIR/plan.md"
+PROGRESS="$DIR/progress.md"
+GRILL="$DIR/grill.md"
+
+emit() {
+    jq -Rs '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:.}}' 2>/dev/null
+}
+
+# Ветка под задачу без папки — работа идёт мимо. Сессию не рвём: SessionStart, отбивающий
+# запуск, оставляет владельца без агента вовсе, а правку кода поймает `task-flow-guard`.
+if [ ! -d "$DIR" ]; then
+    if command -v rt_task_branch_ok >/dev/null 2>&1 && rt_task_branch_ok "$branch"; then
+        {
+            printf 'РАБОТА БЕЗ ПАПКИ ЗАДАЧИ.\n\n'
+            printf 'Ветка `%s` названа задачей, а `%s/` нет: ход работы записывать некуда,\n' "$branch" "$DIR"
+            printf 'и следующий заход начнёт с расспросов владельца.\n\n'
+            printf 'Собрать с образца:\n\n    cp -r %s/_template %s\n\n' "$TASKS_DIR" "$DIR"
+            printf 'Правку кода приложения до этого отбивает гард. Правило — скил `task-flow`.\n'
+        } | emit
+    fi
+    exit 0
+fi
+
+# Порог объёма. Ход работы растёт с каждым заходом, и на десятом заходе целиком он стоит
+# дороже, чем даёт. Перевалив порог, отдаём «Где стоим» и последние записи.
+LIMIT=40000
+size=0
+for file in "$PLAN" "$PROGRESS"; do
+    [ -f "$file" ] || continue
+    size=$((size + $(wc -c <"$file" 2>/dev/null || echo 0)))
+done
+
+{
+    printf 'СОСТОЯНИЕ РАБОТЫ — ветка `%s`, папка `%s/`.\n\n' "$branch" "$DIR"
+    printf 'Это записано прошлыми заходами. Владельца о том, что здесь есть, не спрашивают.\n'
+    printf 'Отметка о сделанном — только в `progress.md`; `plan.md` по ходу не правится.\n'
+    printf 'Как ведётся работа — правило `task-flow`, возвращение к ней — паттерн `task-flow-resume`.\n\n'
+
+    if [ -f "$GRILL" ]; then
+        printf 'Разбор просьбы владельца — `%s`, читается по надобности.\n\n' "$GRILL"
+    fi
+
+    if [ -f "$PLAN" ]; then
+        printf -- '--- ЗАМЫСЕЛ (`%s`) ---\n\n' "$PLAN"
+        if [ "$size" -le "$LIMIT" ]; then
+            cat "$PLAN"
+        else
+            sed -n '1,60p' "$PLAN"
+            printf '\n<обрезано по объёму — читается целиком: %s>\n' "$PLAN"
+        fi
+        printf '\n'
+    fi
+
+    if [ -f "$PROGRESS" ]; then
+        printf -- '--- ХОД РАБОТЫ (`%s`) ---\n\n' "$PROGRESS"
+        if [ "$size" -le "$LIMIT" ]; then
+            cat "$PROGRESS"
+        else
+            # Раздел «Где стоим» перезаписывается каждым заходом и переживает любой объём.
+            awk '/^## Где стоим/{f=1} f&&/^## /&&!/^## Где стоим/{exit} f' "$PROGRESS"
+            printf '\n<обрезано по объёму. Последние записи:>\n\n'
+            tail -40 "$PROGRESS"
+            printf '\n<читается целиком: %s>\n' "$PROGRESS"
+        fi
+    fi
+} | emit

package/assets/hooks/task-flow-guard.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+# rt-hook: PreToolUse Edit|Write|MultiEdit
+# PreToolUse guard for Edit|Write|MultiEdit: код не пишется раньше замысла.
+#
+# Работа идёт много заходов, и между ними исполнитель не помнит ничего. Замысел, лежащий на
+# диске, — единственное, что переживает перерыв: изменения к этому моменту бывают не
+# закоммичены, отчёт не открыт, а очередь работ показывает задачу начатой и молчит о том, что
+# внутри неё сделано.
+#
+# Гард требует три вещи и ровно их: папку задачи по имени ветки, замысел в ней и названную в
+# замысле договорённость о продукте. Полноту написанного он не судит — это за владельцем
+# (решения в законе `docs/constitution/work-conduct.md`).
+#
+# Правило целиком — скил `task-flow`.
+#
+# Осознанный выход есть: строка `**Поведение:** не меняется — <причина>` в замысле снимает
+# требование договорённости. Пустая причина не принимается, как и у `Docs-skip:`.
+#
+# FAIL-OPEN: нет jq, не git-репозиторий, битый ввод, чужой инструмент → пропуск. Сломанный
+# гард не должен мешать работать.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+command -v jq >/dev/null 2>&1 || exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+case "$tool" in
+    # Инструмент редактора заводит файл теми же двумя данными, только называет их иначе —
+    # без этой ветки правка шла бы мимо гарда сменой инструмента.
+    Edit | Write | MultiEdit | mcp__webstorm__create_new_file) ;;
+    *) exit 0 ;;
+esac
+
+path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // .tool_input.pathInProject // empty' 2>/dev/null)"
+[ -z "$path" ] && exit 0
+case "$path" in
+    /*) ;;
+    ?*) path="${CLAUDE_PROJECT_DIR:-.}/$path" ;;
+esac
+
+# Профиль дерева: сперва умолчание пакета, поверх него — надстройка проекта, если она есть.
+rt_hooks_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+for profile in "$rt_hooks_dir/../rt-kit/defaults/project.sh" "$rt_hooks_dir/../defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/defaults/project.sh" "${CLAUDE_PROJECT_DIR:-.}/.claude/rt-kit/project.sh"; do
+    # shellcheck disable=SC1090
+    [ -f "$profile" ] && . "$profile" 2>/dev/null
+done
+
+# Признак «правка меняет поведение» — путь, а не оценка на глаз: оценку назначает тот, кому
+# она мешает, и порог плывёт. Где живёт код приложения, знает профиль: правила, тексты, обвязка
+# и зависимости под требование не попадают — иначе разбор задачи нельзя было бы вести до
+# заведения ветки.
+command -v rt_is_app_code >/dev/null 2>&1 || exit 0
+rt_is_app_code "$path" || exit 0
+
+# Каталог папок задач: у дерева он свой, но имя обычно общее.
+tasks_dir="${RT_TASKS_DIR:-docs/tasks}"
+
+deny() {
+    jq -n --arg r "$1" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}' 2>/dev/null \
+        || printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$1"
+    exit 0
+}
+
+# Ветку смотрим там же, где пойдёт правка: у worktree она своя.
+workdir="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null)"
+[ -z "$workdir" ] && workdir="${CLAUDE_PROJECT_DIR:-.}"
+cd "$workdir" 2>/dev/null || exit 0
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+branch="$(git branch --show-current 2>/dev/null)"
+[ -z "$branch" ] && exit 0   # detached HEAD — не про наш случай
+
+if command -v rt_task_branch_ok >/dev/null 2>&1 && ! rt_task_branch_ok "$branch"; then
+    deny "BLOCKED by task-flow: правка кода идёт в ветке под задачу, а текущая ветка — '${branch}'. Заведи задачу (npm run task:new -- --title '…' --slug <slug>) и ветку под её номером, затем повтори. Правило — скил task-flow."
+fi
+
+root="$(git rev-parse --show-toplevel 2>/dev/null)"
+[ -z "$root" ] && exit 0
+dir="$root/$tasks_dir/$branch"
+plan="$dir/plan.md"
+
+if [ ! -f "$plan" ]; then
+    deny "BLOCKED by task-flow: нет замысла — '${tasks_dir}/${branch}/plan.md'. Собери папку задачи с образца (cp -r ${tasks_dir}/_template ${tasks_dir}/${branch}) и заполни шапку, след задачи и этапы, затем повтори. Правило — скил task-flow."
+fi
+
+# Строка обхода: поведение не меняется, договорённость о продукте не нужна. Причина обязана
+# стоять — без неё обход становится умолчанием.
+if grep -qE '^\*\*Поведение:\*\*[[:space:]]*не меняется[[:space:]]*—[[:space:]]*\S' "$plan" 2>/dev/null; then
+    exit 0
+fi
+
+draft="$(sed -n 's/^\*\*Драфт:\*\*[[:space:]]*`\([^`]*\)`.*/\1/p' "$plan" 2>/dev/null | head -1)"
+
+if [ -z "$draft" ]; then
+    deny "BLOCKED by task-flow: в '${tasks_dir}/${branch}/plan.md' не названа договорённость о продукте. Заведи её в docs/specs/<домен>/proposed/<фича>/ и укажи строкой '**Драфт:** \`путь\`'. Если правка поведения не меняет — поставь '**Поведение:** не меняется — <причина владельца>'. Правило — скил task-flow."
+fi
+
+case "$draft" in
+    /*) draft_path="$draft" ;;
+    *) draft_path="$root/$draft" ;;
+esac
+
+if [ -e "$draft_path" ]; then
+    exit 0
+fi
+
+# Договорённость, влитая в спек домена, с диска уходит — так и задумано: в главной ветке
+# директории «предложено» быть не должно. Но замысел на неё ссылается до конца работы, и без
+# этой развилки последний коммит отчёта запирал бы ветку: ни правки по замечаниям разбора, ни
+# записи в журнал изменений после вливания уже не сделать.
+#
+# Влитое от незаведённого отличает история ветки: путь, которого в ней никогда не было,
+# договорённостью не был. Спросить об этом нечем, кроме git, поэтому нет git — отказ остаётся.
+if git -C "$root" log --oneline -1 -- "$draft" 2>/dev/null | grep -q .; then
+    exit 0
+fi
+
+deny "BLOCKED by task-flow: замысел называет договорённость '${draft}', а её на диске нет и в истории ветки не было. Заведи её с образца (docs/specs/_template) или поправь путь в '${tasks_dir}/${branch}/plan.md'. Правило — скил task-flow."

package/assets/laws/{access.md → application/access.md}

@@ -1,4 +1,4 @@
-# Доступ
+# Закон о доступе
 
 Кто что может делать: вход владельца, права на действия, поведение публичных путей.
 Правила держат все процедуры контракта и все разделы админки.
@@ -32,6 +32,3 @@
 - **Пока права не получены, админка ничего не прячет.** Пустая шапка после сетевого сбоя
   выглядит как сломанная админка и не оставляет выхода; запрос без права всё равно
   отобьётся на сервере.
-- **Отобранное право перестаёт действовать не позже, чем истекает вход.** Права, вписанные во
-  вход и живущие до его конца, оставляют раздел открытым тому, у кого право уже забрали, — и
-  тем дольше, чем длиннее вход. Отзыв, который замечают только при следующем входе, — не отзыв.

package/assets/laws/{locales.md → application/locales.md}

@@ -1,4 +1,4 @@
-# Локали и переводы
+# Закон о локалях и переводах
 
 Как в системе устроены языки: адреса публичного сайта, подписи интерфейса, переводы
 контента и язык админки. Правила держат сайт, админку, письма и документ-подтверждение
@@ -31,5 +31,3 @@
   ввода при сохранении объекта.
 - **У локали есть начальная валюта показа.** Дальше валюту выбирает гость, и его выбор
   сильнее умолчания локали.
-- **Локаль страницы определяется её адресом, а не языком браузера.** Иначе один адрес отдаёт
-  разным гостям разный текст, и кэшировать его нечем: в кэш попадает то, что увидел первый.

package/assets/laws/application/money.md

@@ -0,0 +1,41 @@
+# Закон о деньгах
+
+Как в системе устроены суммы. Правила держат расчёт цены, заказы, письма, документы-основания
+и сводки одновременно, и разойтись им нельзя: сумма, названная в трёх местах по-разному, — это
+не три числа, а одно сломанное.
+
+## Терминология
+
+| Термин          | Определение                                                                     |
+| --------------- | ------------------------------------------------------------------------------- |
+| Валюта хранения | Единственная валюта, в которой сумма записана и посчитана. Одна на всю систему  |
+| Валюта показа   | Валюта, в которой сумму видит пользователь. Может отличаться от валюты хранения |
+| Подытог         | Сумма до скидок                                                                 |
+| Итог            | Сумма после применённой скидки — то, что называется ценой                       |
+
+## Статьи
+
+- **Сумма хранится в целых единицах валюты хранения.** Дробная часть даёт расхождение между
+  подытогом и итогом: то, что показано построчно, перестаёт складываться в то, что показано
+  внизу. Если дробная часть в предметной области значима, единицей хранения становится она
+  сама, а не доля от целого.
+- **Валюта хранения одна на систему, и она объявлена.** Две валюты хранения означают, что
+  каждое сравнение сумм — это скрытый пересчёт по курсу, которого в момент сравнения может не
+  быть вовсе.
+- **Округление происходит один раз — при расчёте цены.** Сумма на экране, сумма в письме и
+  сумма в хранилище — одно и то же число, а не три результата одного пересчёта.
+- **Из подходящих скидок применяется одна — наибольшая.** Сложение дало бы суммы, которых
+  никто не закладывал, и объяснить пользователю итог стало бы нечем.
+- **При равной выгоде побеждает та скидка, которую пользователь ввёл руками.** Он ждёт
+  подтверждения своему действию, а «код не сработал» при той же итоговой цене читается как
+  поломка.
+- **Скидка не уводит цену ниже нуля.** Скидка суммой ограничена самим подытогом.
+- **Пересчёт в чужую валюту не хранится.** Хранится сумма в валюте хранения и код валюты
+  показа; само число вычисляется на показ. Сохранённое устарело бы вместе с курсом, а по виду
+  оставалось бы точным.
+- **Оплата идёт в валюте хранения; остальные валюты — справка.** Ни подтверждение, ни документ
+  не называют справочное число суммой к оплате.
+- **Валюта показа следует за пользователем.** Он выбрал её на экране — в письме сумма
+  пересчитана в неё же. Письмо в другой валюте читается как другая цена.
+- **Курс недоступен — сумма показывается в валюте хранения без пересчёта.** Пересчёт по
+  неизвестно какому курсу хуже отсутствующего: отсутствие видно, а неверный курс — нет.

package/assets/laws/application/ownership.md

@@ -0,0 +1,32 @@
+# Закон о владеющей сущности
+
+Как система ведёт себя, когда владеющих сущностей больше одной. Владеющая сущность — та, кому
+принадлежат записи остальных доменов: площадка, объект, организация, точка. Правило держат все
+эти домены сразу, и разойтись им нельзя.
+
+## Терминология
+
+| Термин             | Определение                                                                                                               |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| Владеющая сущность | Запись, которой принадлежат записи остальных доменов. Не настройка: у неё свой идентификатор, свои права и своя видимость |
+| Действующая        | Та, что видна пользователю снаружи                                                                                        |
+| Скрытая            | Заведённая, но снаружи не показанная. Её записи никуда не деваются                                                        |
+| Сводка             | Экран, отвечающий сразу по всем действующим: очередь работ, статистика, дашборд                                           |
+
+## Статьи
+
+- **Запись принадлежит владеющей сущности, а не системе.** Настроек, действующих сразу на все,
+  нет: заведение второй сущности не меняет поведение первой.
+- **Пустой идентификатор в запросе означает единственную действующую.** Пока она одна, клиент
+  вправе её не называть — и не обязан меняться в тот день, когда появится вторая.
+- **При двух и более действующих запрос обязан назвать сущность.** Умолчание перестаёт быть
+  однозначным, и запрос отбивается как неверный, а не выбирает первую попавшуюся.
+- **Названная явно находится, даже если она скрыта.** У скрытой остаются записи, деньги и
+  переписка, и добраться до них надо как раз тогда, когда снаружи её уже нет.
+- **Там, где показана сводка, пустой идентификатор означает все действующие.** Очередь работ,
+  статистика и дашборд отвечают по всему набору, а не требуют сперва выбрать одну.
+- **Когда действующих нет вовсе, запрос отбивается.** Скрытая вместо отсутствующей действующей
+  не подставляется: показанное в этот момент выглядело бы работающим, а на деле показывало бы
+  снятое с показа.
+- **Выбор сущности виден на экране и действует на всё, что говорит об одной.** Пользователь,
+  который не видит, о какой сущности идёт речь, читает чужие числа как свои.

package/assets/laws/{search-visibility.md → application/search-visibility.md}

@@ -1,4 +1,4 @@
-# Видимость в поиске
+# Закон о видимости в поиске
 
 Как публичный сайт выглядит для поисковика. Страница живёт в нескольких языках под одним
 доменом, и от разметки зависит, считает поисковик эти адреса одной страницей на разных

package/assets/laws/code-structure.md

@@ -1,4 +1,4 @@
-# Устройство кода
+# Закон об устройстве кода
 
 Что должно быть верно про сам код независимо от того, что он делает. Закон нужен потому, что
 код читают чаще, чем пишут: имя, по которому не видно рода объявления, и тип, объявленный
@@ -8,14 +8,15 @@
 
 - **Имя объявления говорит, какого оно рода.** Без этого род объявления выясняется переходом
   к нему, и на каждом чтении заново.
+- **Имя файла, обещающее род объявления, это объявление в нём находит.** Списки, деревья
+  каталогов и сообщения об ошибках показывают имя вместо содержимого, и обещание, которого
+  файл не держит, обходится дороже отсутствующего.
 - **Источник значения, за которым следят, виден по его имени.** Иначе подписка на него
   выглядит как обычное чтение, и её забывают снять.
 - **Тип берётся из того пакета, где объявлен.** Своя копия чужого типа расходится с
   оригиналом молча, а компилируется из них только одна.
+- **Значение не объявляется подходящим в обход проверки типа.** Приведение через промежуточное
+  «неизвестно» отключает сверку намеренно и принимает что угодно; там, где иначе нельзя,
+  причина названа рядом.
 - **Отметка об устаревании — повод убрать, а не повод оставить.** Устаревшее объявление,
   которое молча продолжает работать, переживает того, кто его пометил.
-- **Значение проверяется, а не объявляется подходящим.** Объявить значение подходящим можно
-  где угодно и о чём угодно: это принимает любую строку и компилируется, а расходится с
-  правдой уже на работающем приложении.
-- **Имя файла говорит, что в нём лежит.** Файл под чужим именем находится поиском, а
-  открывается не тем, чего от него ждали, — и так на каждом чтении заново.

package/assets/laws/delivery.md

@@ -1,4 +1,4 @@
-# Поставка
+# Закон о поставке
 
 Как правка доезжает до работающего приложения. Закон держит и историю изменений, и то, что
 в этот момент видит пользователь: неудачная выкатка отличается от удачной только тем, что
@@ -6,15 +6,65 @@
 
 ## Статьи
 
+- **Правка начинается с задачи, видимой в очереди работ.** Заведённой задачи мало: ту, что в
+  очередь не попала, никто не видит, и работа за ней не планировалась.
 - **Правка попадает в главную ветку только через отдельную ветку.** Прямая запись в главную
   лишает правку и обсуждения, и возможности откатить её одним движением.
+- **У задачи одна ветка, у ветки одна задача.** Откат снимает всё, что въехало этой веткой,
+  разом: две задачи в ней откатятся только вместе, а задача, въехавшая двумя ветками, после
+  отката одной останется наполовину сделанной — и в очереди работ этого не видно. Работа,
+  которая в одну ветку не влезает, делится на задачи до того, как ветка заводится. Признак
+  деления — раздельный откат, а не объём: числа файлов, строк или коммитов, за которым работа
+  становится двумя задачами, нет. Правка одного рода остаётся одной задачей, сколько бы файлов
+  она ни задела.
+- **Две задачи, которые чинятся одной правкой, — одна задача.** Вторая стирается вместе со
+  своим номером, а то, чего в первой не было, дописывается в неё до этого. Две строки об
+  одной работе хуже дыры в нумерации: по ним потом не понять, что сделано, а что нет. Слить
+  их можно, пока правка не въехала в главную ветку; после — обе остаются как есть.
+- **Задача, ветка под неё и отчёт о сделанном несут один и тот же номер в своих названиях.**
+  Иначе одну работу приходится узнавать по тексту названия, а в списке из полусотни строк это
+  делается по памяти и с ошибками.
+- **Номер пишется всюду одинаково: ключ задач, дефис, номер.** Заголовок задачи и отчёта
+  начинается с этой пары в квадратных скобках, имя ветки — с неё же. Одна форма, а не три
+  похожих, потому что номер читают не только глазами: из имени ветки его достаёт гард, из
+  заголовка — сверка очереди. Формы, выведенные порознь, расходятся молча и не отказывают, а
+  перестают узнавать номер: проверка, которая должна была найти работу без задачи, пропускает
+  всё подряд.
+- **Ключ задач дерево называет само, но назвать обязано.** В форме имени это единственное, что
+  у каждого дерева своё, — и единственное, что настраивается. Не названный ключ не даёт ни
+  поблажки, ни умолчания: работа с очередью отказывает и говорит, где он задаётся. Пустой ключ
+  хуже отсутствующей проверки — от имени остаётся огрызок, которому ничто не отвечает, и
+  правильно названной не выглядит ни одна задача.
+- **У задачи есть исполнитель с момента её заведения.** Задача без исполнителя выглядит
+  ничьей: по очереди работ не видно, кто её взял, и заведённая по ходу правка теряется среди
+  чужих.
+- **Состояние задачи в очереди работ отвечает тому, что с ней происходит.** Взятая в работу
+  видна взятой, а та, отчёт по которой ждёт разбора, — ждущей разбора. Иначе очередь показывает
+  один и тот же вид у нетронутого, у делаемого прямо сейчас и у сделанного: работа берётся
+  второй раз, а отчёт стоит неразобранным, пока про него не вспомнят. Состояние переставляется
+  в тот момент, когда работа переходит на следующий шаг, а не приводится в порядок потом:
+  очередь читают между этими моментами, а не после них.
 - **Попадание правки в главную ветку означает выкатку.** Всё, от чего правка зависит снаружи
   кода — переменные окружения, секреты, записи имён, — ставится до этого момента, а не после.
+- **Признак режима исполнения объявлен в самом артефакте развёртывания, а не только в составе
+  его запуска.** Артефакт поднимают и мимо состава — руками, при разборе, на чужой машине, — и
+  без объявления он в этот момент считает себя отладочным, не сказав об этом ничего.
 - **Выкатывается образ того коммита, который выкатывают.** Умолчание «последний» отстаёт от
   главной ветки, и приложение молча возвращается к прежней версии, продолжая отвечать.
+- **Из одного и того же коммита всегда ставятся одни и те же зависимости.** Если версия задана
+  диапазоном, установка сегодня и установка через неделю дадут разный код: сборка сломается
+  сама собой, и откатывать будет нечего. Обновление зависимости — обычная правка: у неё есть
+  автор, описание и откат.
 - **Порядок изменений хранилища проверяется с пустого места.** На уже работающем хранилище
   неверный порядок незаметен: он проявляется только при развёртывании с нуля.
+- **Проверка перед отправкой смотрит на содержимое репозитория, а не на состояние машины, где
+  она запущена.** На машине законно лежат недоделки, личные настройки и файлы вне истории.
+  Проверка, которая их читает, отбивает правку из-за того, чего в репозитории нет, и молчит о
+  том, что в нём есть. Проверка перед отправкой и конвейер выкатки судят по одному и тому же —
+  иначе «сошлось» значит в этих двух местах разное.
 - **Документ едет вместе с правкой, которую он описывает.** Ни сборка, ни проверки текстов
   не читают, поэтому расхождение копится молча и потом выглядит действующей справкой.
-- **Отдельная ветка называет задачу, которую закрывает.** Иначе связь правки с причиной живёт
-  только в памяти автора, и через полгода по истории не сказать, зачем это сделано.
+- **Отчёт о сделанном остаётся верным до самого слияния.** Он описывает дерево на день, когда
+  его написали, а разбора ждёт днями: за это время главная ветка вливается в ветку, и
+  утверждение отчёта о соседних файлах становится неправдой молча — тел отчётов не читает ни
+  одна проверка. Всё, что вливается в ветку после публикации отчёта, — повод перечитать его.

package/assets/laws/entity-editing.md

@@ -1,60 +1,54 @@
-# Правка сущности
+# Закон о правке сущности
 
-Как ведёт себя приложение, когда владелец создаёт или меняет запись: объект, бронь,
-подписку на календарь, адрес страницы. Поведение одинаково во всех разделах админки и ни
-одному домену не принадлежит — спек домена описывает только то, что у него своего.
+Как ведёт себя приложение, когда пользователь создаёт или меняет запись. Ведёт оно себя
+одинаково везде, где правят записи: это общее поведение, а не особенность одной его части.
 
-Попадание в запись из набора и объём запрашиваемых данных — предмет других законов.
+Попадание в запись из списка и объём запрашиваемых данных — предмет других законов.
 
 ## Статьи
 
-- **Асайд закрывается только после успешного запроса.** Закрытие — сигнал «сохранено»,
-  и закрыть его до ответа значит соврать.
-- **Пока запрос идёт, кнопка сохранения показывает спиннер и недоступна.** Второе нажатие
-  иначе шлёт второй запрос по той же форме.
-- **Отказ остаётся внутри асайда, рядом с полями.** Асайд не закрывается, введённое
-  сохраняется, кнопка снова доступна — владелец правит и повторяет, а не набирает заново.
-- **Новый запрос гасит прежнюю ошибку.** Иначе рядом с работающей формой висит сообщение
-  о прошлой неудаче.
-- **Создание закрывает асайд всегда, редактирование — по решению экрана.** Созданной
-  записи на экране ещё нет, и оставаться в форме не над чем; при правке экран может
-  оставить асайд открытым и перечитать запись.
-- **Успешная правка подтверждается тостом.** Закрывшийся асайд сам по себе не говорит,
-  сохранилось ли, — особенно когда список за ним обновляется не сразу.
-- **Кнопка записи недоступна, пока в форме ничего не изменили.** Иначе владелец отправляет
-  запрос без правок и получает подтверждение ни о чём.
-- **Закрытие панели с несохранёнными правками спрашивает, что с ними сделать: закрыть без
-  сохранения, закрыть с сохранением или остаться.** Вопрос задаётся на каждом из четырёх
-  путей закрытия.
-- **Кнопка закрытия называет судьбу правок: «Закрыть и не сохранять» на панели с записью и
-  «Закрыть» на панели только для просмотра.**
-- **Ссылка на запись, которой уже нет, не оставляет пустой панели.**
-- **Панель узнаёт, что показывать, из адреса: идентификатор записи стоит в нём.** Иначе панель не
-  открыть по ссылке и не восстановить после перезагрузки.
-- **У панели есть шапка с заголовком и футер, и в футере хотя бы кнопка закрытия.**
-- **Заголовок панели называет действие, а имя записи стоит надстрочником над ним.** Заголовок
-  из одного названия записи не говорит, что сейчас произойдёт.
-- **Создание и правка названы в заголовке по-разному.**
-- **Связанная запись открывается из панели ссылкой.**
-- **Переход по ссылке из панели с несохранёнными правками спрашивает о них так же, как
-  закрытие.**
-- **Кнопка записи в футере одна: «Создать» при создании, «Сохранить» при правке.** Она стоит у
-  противоположного края от кнопки закрытия.
-- **Панель закрывается четырьмя путями: кнопкой в шапке, кнопкой в футере, нажатием мимо неё и
-  клавишей Esc.**
-- **Закрытая панель нажатий не перехватывает.** Она стоит за краем экрана, ничего не видно, и
-  страница под ней перестала бы отвечать на нажатия молча.
-- **Прокручивается только содержимое: шапка и футер видны всегда.**
-- **Поля во всех панелях отбиты от края одинаково и получают одну ширину.** Прокручивается
-  при этом всё содержимое целиком, поэтому обводка фокуса у крайнего поля видна полностью.
-- **Пока запись читается, поля показаны скелетонами.**
-- **Запись, которую можно только смотреть, показана данными, а не полями ввода.** Поле ввода,
-  которое не принимает ввод, владелец сначала пробует заполнить.
-- **Непонятное объясняется на месте: подсказкой под полем или сообщением над формой.**
-- **Действия над записью доступны из самой записи, а не только из набора.** Они стоят в шапке
-  панели и при числе больше двух прячутся под одну кнопку меню; иначе открытая запись — тупик,
-  из которого приходится возвращаться в набор ради каждого действия.
-- **Длинная форма разложена вкладками, и вкладки остаются на месте при прокрутке.** Разделы
-  подряд одной полосой требуют прокрутить всю форму до нижнего.
-- **Действий, относящихся к содержимому одной вкладки, не заводится.** С закрытой вкладки
-  такое действие не видно, а на открытой спорит с общей кнопкой записи.
+- **Форма закрывается только после того, как запись сохранена.** Закрытие означает
+  «сохранено», поэтому закрывать её до ответа сервера нельзя.
+- **Пока идёт сохранение, отправить форму второй раз нельзя, и пользователь видит, что запрос
+  ещё не закончился.** Иначе повторное нажатие отправит те же данные ещё раз.
+- **Если сохранить не удалось, введённое остаётся на месте.** Ошибка показана рядом с полями,
+  форма открыта, и пользователь исправляет данные, а не набирает их заново.
+- **Новая попытка убирает сообщение о прошлой ошибке.** Иначе рядом с работающей формой висит
+  сообщение о неудаче, которой уже нет.
+- **После создания форма закрывается всегда, после изменения — по решению экрана.** Новой
+  записи на экране ещё нет, и держать форму открытой не над чем; при изменении экран может
+  оставить её открытой и перечитать запись.
+- **Об успехе говорит сообщение, а не то, что форма исчезла.** По одному закрытию непонятно,
+  сохранилось ли, — тем более что список за формой обновляется не сразу.
+- **Форму, в которой ничего не меняли, отправить нельзя.** Иначе пользователь шлёт запрос без
+  правок и получает подтверждение того, чего не делал.
+- **Если пользователь уходит с несохранёнными правками, приложение спрашивает, что с ними
+  делать.** Ответа три: уйти без сохранения, сохранить и уйти, остаться. Спрашивается это,
+  каким бы способом пользователь ни уходил.
+- **По подписи действия, которое уводит с формы, понятно, что станет с введённым.** Если на
+  форме с правками и на форме только для просмотра написано одно и то же слово, пользователь
+  не знает, потеряет он введённое или нет.
+- **Если запись по ссылке уже удалена, пользователь видит объяснение, а не пустой экран.**
+- **Какую запись показывать, форма берёт из адреса.** Иначе её не открыть по ссылке и не
+  восстановить после перезагрузки.
+- **При прокрутке длинной формы её название и её действия остаются на виду.**
+- **По названию формы понятно, что сейчас произойдёт, а не только с какой записью работает
+  пользователь.** По одному имени записи непонятно, создают её или меняют.
+- **Создание и изменение названы по-разному.**
+- **Сохранить введённое можно одним действием.** Оно стоит в стороне от того, которое уводит с
+  формы, чтобы их не перепутали.
+- **Уйти с формы можно несколькими способами:** мышью, с клавиатуры и нажатием вне формы.
+- **Закрытая форма нажатий не перехватывает.** Её не видно, а страница под ней перестала бы
+  отвечать без всякого объяснения.
+- **У всех полей формы одинаковые отступы от края и одинаковая ширина.** Содержимое
+  прокручивается целиком, поэтому рамка фокуса у крайнего поля не обрезается.
+- **Пока запись загружается, на месте полей показано, что идёт загрузка.**
+- **Запись, которую нельзя менять, показана текстом, а не полями ввода.** Поле, которое не
+  принимает ввод, пользователь сначала пробует заполнить.
+- **На связанную запись можно перейти прямо из формы.** Переход — такой же уход с формы, как
+  закрытие, поэтому о несохранённых правках спрашивается так же; выбравшему сохранить и уйти
+  связанная запись открывается после успешного сохранения.
+- **Пояснение стоит рядом с тем, что вызвало вопрос.**
+- **Отправляемость формы и вопрос при уходе решаются одним признаком.** Два разных ответа на
+  вопрос «изменилось ли что-нибудь» рано или поздно расходятся, и форма либо шлёт пустую
+  правку, либо молча теряет введённое.

package/assets/laws/entity-models.md

@@ -1,10 +1,10 @@
-# Модели сущностей
+# Закон о моделях сущностей
 
 Сколько данных приложение запрашивает и отдаёт на каждом экране: строка списка, открытая
-запись, пункт выпадающего списка. Одна и та же сущность выглядит на них по-разному, и разница
-эта не украшение — от неё зависит, сколько владелец ждёт список.
+запись, пункт выпадающего списка. Одна и та же сущность выглядит на них по-разному, и
+разница эта не украшение — от неё зависит, сколько пользователь ждёт список.
 
-Как список показывает записи и как ведёт себя панель правки — предмет других законов.
+Как список показывает записи и как ведёт себя форма правки — предмет других законов.
 
 ## Статьи
 
@@ -15,13 +15,3 @@
 - **Между сторонами стоит перевод, и экраны читают только вторую.**
 - **Пустое значение выражается пустой строкой или нулём, а не отсутствием поля.** Необязательных
   скаляров в контракте нет, и «не задано» у каждого поля значит своё.
-- **У сущности два уровня: короткий и полный.** Короткий — для строки набора, выпадающего
-  списка и подсказок ввода, полный — для открытой записи. Одна модель на все случаи тянет в
-  набор то, что в нём не показано: изображения, длинные тексты, вложенные наборы.
-- **Следующий уровень расширяет предыдущий, а не повторяет его поля.** Повторённое поле
-  расходится при первой же правке, и какое из двух объявлений верное — не видно.
-- **Контракт различает короткое сообщение набора и полное сообщение записи.** Одно сообщение
-  на оба случая делает выбор уровня невозможным: лишнее приезжает независимо от того, кто
-  спрашивает.
-- **Открытая запись читается своим запросом по идентификатору.** Взятая из уже загруженного
-  набора, она открывается по ссылке только после того, как загрузится весь набор.