@rt-tools/agent-kit 0.4.0 → 0.5.1

package/assets/hooks/git-guard-delivery.sh

@@ -79,6 +79,14 @@ title_re="${RT_TASK_TITLE_RE:-^\[[A-Za-z]+-[0-9]+\][[:space:]]+[^[:space:]]}"
 task_new="${RT_TASK_NEW_CMD:-npm run task:new}"
 board_check="${RT_BOARD_CHECK_CMD:-npm run check:board}"
 task_bot="${RT_TASK_BOT:-}"
+tasks_dir="${RT_TASKS_DIR:-}"
+archive_dir="${RT_ARCHIVE_DIR:-}"
+main_branch="${RT_MAIN_BRANCH:-main}"
+
+# Обход требования: строка с причиной. Причина видна тому, кто вливает, поэтому обход законен.
+# Без причины это просто молчаливый пропуск, поэтому она обязательна. Порог в три знака — тот
+# же, что у гарда документа: если сделать по-разному, две формы одного обхода разойдутся.
+folder_skip_re='Task-folder-skip:[[:space:]]*[^[:space:]"'"'"']{3,}'
 
 deny() {
     jq -n --arg r "$1" '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}' 2>/dev/null \
@@ -86,6 +94,21 @@ deny() {
     exit 0
 }
 
+# Подсказка вместо отказа: на открытии отчёта папка ещё нужна. Решения подсказка не несёт,
+# команда идёт дальше своим ходом.
+hint() {
+    jq -n --arg c "$1" '{hookSpecificOutput:{hookEventName:"PreToolUse",additionalContext:$c}}' 2>/dev/null
+    exit 0
+}
+
+# Есть ли папка задачи в ветке. Смотрим содержимое ветки, а не рабочее дерево: если папку
+# удалили, но не закоммитили, проверка прошла бы, а папка всё равно уехала бы в main. Имя
+# ветки подставляем целиком, вместе с косой: у ветки вида `chore/312-slug` папка лежит во
+# вложенном каталоге.
+folder_in_branch() {
+    git ls-tree -d --name-only HEAD -- "$1" 2>/dev/null | head -1
+}
+
 check_task() {
     number="$1"
     where="$2"
@@ -127,11 +150,62 @@ if [ -n "$branch_arg" ]; then
     exit 0
 fi
 
+# --- слияние заявки ----------------------------------------------------------------------
+#
+# Папку задачи разбирают тем же PR, что и работу. После слияния этого уже никто не сделает:
+# работа перешла к следующей задаче, а PR закрыт. Раньше слияния требовать нельзя — пока идёт
+# ревью, plan.md нужен на диске, иначе гард хода работы не даст править код.
+# Команду ищем от начала строки или после разделителя, а не где угодно в тексте. Иначе гард
+# отбивает сообщение, где `gh pr merge` просто упомянут в кавычках, — так он и сработал на
+# правке этого же текста. Полностью подстроку в кавычках так не отсечь, но случайное упоминание
+# внутри слова или пути мимо уже не пройдёт.
+if printf '%s' "$cmd" | grep -qE '(^|[;&|(]|&&|\|\|)[[:space:]]*(gh[[:space:]]+pr[[:space:]]+merge|glab[[:space:]]+mr[[:space:]]+merge|az[[:space:]]+repos[[:space:]]+pr[[:space:]]+update)([[:space:]]|$)'; then
+    [ -n "$tasks_dir" ] || exit 0   # ведения работы папкой в дереве нет
+
+    merge_branch="$(git branch --show-current 2>/dev/null)"
+    [ -z "$merge_branch" ] && exit 0
+    rt_task_branch_ok "$merge_branch" || exit 0   # за беззадачной веткой папки не стоит
+
+    folder="$tasks_dir/$merge_branch"
+
+    # Сначала ищем обход в самой команде — это работает и без сети. Если читать только
+    # тело PR, то без сети гард отбил бы слияние, причина которого в этом теле и написана.
+    printf '%s' "$cmd" | grep -qiE "$folder_skip_re" && exit 0
+
+    merge_number="$(printf '%s' "$cmd" | sed -nE 's/.*(pr|mr)[[:space:]]+(merge|update)[[:space:]]+([0-9]+).*/\3/p' | head -1)"
+    if [ -n "$merge_number" ] && command -v rt_report_body >/dev/null 2>&1; then
+        body="$(cd "$root" && rt_report_body "$merge_number" 2>/dev/null)"
+        [ -n "$body" ] && printf '%s' "$body" | grep -qiE "$folder_skip_re" && exit 0
+    fi
+
+    lying="$(folder_in_branch "$folder")"
+    [ -n "$lying" ] \
+        && deny "BLOCKED: в ветке осталась папка задачи «${lying}» — она уедет в главную. Разобрать её потом будет некому: работа перейдёт к следующей задаче, а этот PR закроется. Перенеси в «${archive_dir:-архив}» то, что объясняет принятые решения, остальное удали и повтори. Если работа вливается частями, поставь в тело PR строку «Task-folder-skip: <причина>»."
+
+    # Запись в архиве спрашиваем только у ветки, которая папку удалила. Иначе проверка
+    # цеплялась бы к работе, у которой папки и не было. Без общего предка с главной веткой
+    # сравнивать не с чем — тогда молчим.
+    [ -n "$archive_dir" ] || exit 0
+    base="$(git merge-base "$main_branch" HEAD 2>/dev/null)"
+    [ -z "$base" ] && exit 0
+
+    had="$(git ls-tree -d --name-only "$base" -- "$folder" 2>/dev/null | head -1)"
+    [ -z "$had" ] && had="$(git log "$base..HEAD" --diff-filter=A --name-only --pretty=format: -- "$folder" 2>/dev/null | head -1)"
+    [ -z "$had" ] && exit 0
+
+    gained="$(git diff --name-only --diff-filter=A "$base" HEAD -- "$archive_dir" 2>/dev/null | head -1)"
+    [ -z "$gained" ] \
+        && deny "BLOCKED: папку задачи удалили, но в «${archive_dir}» ветка ничего не добавила. Удалить проще, чем разобрать, — и вместе с папкой пропадает разбор просьбы, единственная запись слов владельца. Перенеси то, что объясняет принятые решения, одним файлом с понятным именем и повтори."
+
+    exit 0
+fi
+
 # --- открытие заявки на слияние ----------------------------------------------------------
-case "$cmd" in
-    *gh\ pr\ create* | *glab\ mr\ create* | *az\ repos\ pr\ create*) ;;
-    *) exit 0 ;;
-esac
+# Команду ищем от начала строки или после разделителя — по той же причине, что и слияние:
+# упоминание в кавычках командой не является.
+printf '%s' "$cmd" \
+    | grep -qE '(^|[;&|(]|&&|\|\|)[[:space:]]*(gh[[:space:]]+pr[[:space:]]+create|glab[[:space:]]+mr[[:space:]]+create|az[[:space:]]+repos[[:space:]]+pr[[:space:]]+create)([[:space:]]|$)' \
+    || exit 0
 
 branch="$(git branch --show-current 2>/dev/null)"
 [ -z "$branch" ] && exit 0   # открепившийся HEAD — не про этот случай
@@ -164,4 +238,13 @@ fi
 
 check_task "$number" "заявка с ветки «${branch}»"
 
+# Сейчас папка ещё нужна: правки по замечаниям ревью идут в эту же ветку, а без plan.md их не
+# пропустит гард хода работы. Поэтому здесь только напоминание. Требование стоит на слиянии —
+# там папка уже не нужна, а вред от неё как раз и наступает.
+if [ -n "$tasks_dir" ]; then
+    lying="$(folder_in_branch "$tasks_dir/$branch")"
+    [ -n "$lying" ] \
+        && hint "В ветке лежит папка задачи «${lying}». Разбери её до слияния, этим же PR: потом за неё уже никто не возьмётся. На слиянии это будет отказ, а не напоминание."
+fi
+
 exit 0

package/assets/hooks/grill-gate.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# rt-hook: Stop
+# Гард разговора: ход, в котором владельцу задан вопрос, не заканчивается, пока за этот же ход
+# не читались законы и правила. Stop.
+#
+# Зачем именно так. Требование «правила читаются до разговора» записано в правиле ведения
+# работы, а исполнения у него не было: все прочие гарды судят правку файла или команду, а
+# вопрос в чат ни тем, ни другим не является. Поймать его можно только на завершении хода —
+# событие получает путь к записи хода и видит его целиком.
+#
+# Перехват инструмента меню вариантов эту дыру не закрывает: вопрос чаще задаётся прозой, и
+# ровно так был задан тот, из-за которого гард заведён.
+#
+# Чтением правил считается любой из трёх путей: загрузка правила, чтение файла законов или
+# правил, поиск по ним. Требовать именно загрузку значило бы гнать на неё там, где хватило
+# одного поиска, — гард мешал бы работе вместо того, чтобы её выправлять.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: при любой ошибке, отсутствии записи хода и повторном заходе ход
+# РАЗРЕШАЕТСЯ (exit 0). Сломанный гард не имеет права заклинить разговор.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Повторный заход по тому же ходу не судится: иначе ход не кончится никогда — гард сказал своё
+# один раз и отпускает.
+active="$(printf '%s' "$input" | jq -r '.stop_hook_active // false' 2>/dev/null)"
+[ "$active" = "true" ] && exit 0
+
+transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)"
+[ -z "$transcript" ] && exit 0
+[ -f "$transcript" ] || 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" "${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
+
+# Подстановка без двоеточия намеренно: заданное пустым — это отказ дерева от требования, и
+# подменять его умолчанием нельзя. Умолчание достаётся только тому, кто не задал переменной
+# вовсе.
+laws_dir="${RT_LAWS_DIR-docs/constitution}"
+rules_dir="${RT_RULES_DIR-.claude/skills}"
+specs_dir="${RT_SPECS_DIR-docs/specs}"
+
+# Дерево, у которого нет ни законов, ни правил, требования не получает: читать нечего.
+[ -z "$laws_dir" ] && [ -z "$rules_dir" ] && exit 0
+
+# Образец, по которому вызов инструмента считается чтением правил. Каталоги идут в него как
+# есть: точка в `.claude` совпадает с любым знаком и лишнего сюда не приводит.
+read_re="$(printf '%s' "$laws_dir|$rules_dir|$specs_dir" | sed 's/^|*//; s/|*$//; s/||*/|/g')"
+[ -z "$read_re" ] && exit 0
+
+# Ход — это всё, что записано после последнего настоящего ввода владельца. Ответ инструмента
+# приходит той же ролью `user`, поэтому строки с `tool_result` вводом не считаются: иначе ходом
+# оказался бы кусок после последнего вызова инструмента, и чтение правил в его начале потерялось
+# бы.
+#
+# Хвост в 400 строк: запись хода растёт всю сессию, а судится только последний ход.
+verdict="$(tail -n 400 "$transcript" 2>/dev/null | jq -s -r --arg re "$read_re" '
+    def is_input:
+        .type == "user"
+        and (((.message.content // []) | if type == "array"
+                then ([.[] | select(.type == "tool_result")] | length)
+                else 0 end) == 0);
+
+    (map(is_input) | rindex(true)) as $i
+    | (if $i == null then . else .[$i + 1:] end) as $turn
+    | [$turn[] | select(.type == "assistant") | (.message.content // [])[] | select(.type == "text") | .text] as $texts
+    | [$turn[] | select(.type == "assistant") | (.message.content // [])[] | select(.type == "tool_use")] as $uses
+    | ($uses | map(
+          (.name == "Skill")
+          or ((.name // "") | test("^(Read|Grep|Glob)$")) and ((.input | tostring) | test($re))
+          or ((.name == "Bash") and ((.input.command // "") | test($re)))
+      ) | any) as $read
+    | (($texts | join("\n")) | test("\\?[[:space:]]*$"; "m")) as $asked_prose
+    | ($uses | map(.name == "AskUserQuestion") | any) as $asked_menu
+    | if ($asked_prose or $asked_menu) and ($read | not) then "ask" else "pass" end
+' 2>/dev/null)"
+
+[ "$verdict" = "ask" ] || exit 0
+
+reason="BLOCKED by grill-gate: в ответе есть вопрос владельцу, а законы и правила за этот ход не читались. Вопрос, ответ на который уже записан, владельцу не задаётся — правило ведения работы. Прогони поиск по словам темы и ответь по найденному; спрашивай только то, что документацией не покрыто:
+
+    grep -rn -i \"<слово темы>\" $laws_dir $rules_dir $specs_dir
+
+Гард судит один ход: следующий заход не отбивается."
+
+jq -n --arg r "$reason" '{decision:"block",reason:$r}' 2>/dev/null \
+    || printf '{"decision":"block","reason":"grill-gate: прочитай законы и правила по теме, прежде чем спрашивать владельца."}\n'
+
+exit 0

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

@@ -100,8 +100,19 @@ case "$draft" in
     *) draft_path="$root/$draft" ;;
 esac
 
-if [ ! -e "$draft_path" ]; then
-    deny "BLOCKED by task-flow: замысел называет договорённость '${draft}', а её на диске нет. Заведи её с образца (docs/specs/_template) или поправь путь в '${tasks_dir}/${branch}/plan.md'. Правило — скил task-flow."
+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
 
-exit 0
+deny "BLOCKED by task-flow: замысел называет договорённость '${draft}', а её на диске нет и в истории ветки не было. Заведи её с образца (docs/specs/_template) или поправь путь в '${tasks_dir}/${branch}/plan.md'. Правило — скил task-flow."

package/assets/hooks/window-fill-guard.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# rt-hook: PostToolUse .*
+# rt-hook: PreToolUse .*
+# Заполнение окна: заход доводится до логической точки заранее, а не обрывается на середине.
+#
+# Зачем именно так. Место, где исполнитель помнит ход работы, ограничено, и заполнив его, он
+# теряет не последнее действие, а всю картину разом. Изнутри захода этот предел не виден ничем:
+# ни одна проверка дерева его не показывает, а сжатие контекста срабатывает, когда доводить
+# работу до точки уже нечем.
+#
+# Гард стоит на двух событиях сразу — разводить его по двум файлам значило бы держать два
+# разбора одной записи и два места, где правится один порог:
+#   PostToolUse — на первом пороге отдаёт напоминание: пора выбирать точку остановки;
+#   PreToolUse  — на втором отбивает всё, кроме записи хода работы, передачи и команд поставки.
+# Место между порогами и есть то, на что закрывается заход: дописать ход работы, написать
+# передачу, закоммитить проверенное.
+#
+# Размер окна берётся из настройки дерева. Из записи захода он не выводится: модель записана
+# там без пометки о расширенном окне, и заход на широкое окно от захода на узкое неотличим.
+#
+# ОТКАЗ В ПОЛЬЗУ РАБОТЫ: нет размера окна, нет записи захода, нет разборщика, битый разбор —
+# работа РАЗРЕШАЕТСЯ (exit 0). Сломанный гард не имеет права заклинить работу.
+
+input="$(cat 2>/dev/null)"
+[ -z "$input" ] && exit 0
+
+command -v jq >/dev/null 2>&1 || 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" "${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
+
+window="${RT_WINDOW_TOKENS:-}"
+case "$window" in
+    '' | *[!0-9]*) exit 0 ;;
+esac
+[ "$window" -gt 0 ] 2>/dev/null || exit 0
+
+warn_pct="${RT_WINDOW_WARN_PCT:-40}"
+stop_pct="${RT_WINDOW_STOP_PCT:-50}"
+tasks_dir="${RT_TASKS_DIR:-docs/tasks}"
+handoff_dir="${RT_HANDOFF_DIR:-.claude/handoff}"
+
+event="$(printf '%s' "$input" | jq -r '.hook_event_name // empty' 2>/dev/null)"
+transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null)"
+[ -n "$transcript" ] || exit 0
+[ -f "$transcript" ] || exit 0
+
+# Заполнение — это последняя запись ответа с расходом: вход, разовая запись в кэш, прочитанное
+# из кэша и вывод. Сумма по всем записям тут не годится вовсе — прочитанное из кэша повторяется
+# в каждой из них, и сумма выходит в разы больше окна.
+#
+# Хвост в 200 строк: запись захода растёт весь заход, а нужна из неё одна последняя строка.
+fill="$(tail -n 200 "$transcript" 2>/dev/null | jq -s -r '
+    [.[] | select(.type == "assistant") | .message.usage | select(. != null)]
+    | last
+    | if . == null then empty
+      else ((.input_tokens // 0) + (.cache_creation_input_tokens // 0)
+            + (.cache_read_input_tokens // 0) + (.output_tokens // 0))
+      end
+' 2>/dev/null)"
+
+case "$fill" in
+    '' | *[!0-9]*) exit 0 ;;
+esac
+
+pct=$((fill * 100 / window))
+fill_k=$((fill / 1000))
+window_k=$((window / 1000))
+
+# --- первый порог: напоминание, работа не отбивается -------------------------------------
+
+if [ "$event" = "PostToolUse" ]; then
+    [ "$pct" -ge "$warn_pct" ] || exit 0
+
+    # Напоминание повторяется не на каждом вызове, а на каждой следующей ступени в пять
+    # процентов: иначе оно занимает то самое место, которое бережёт.
+    step=$(((pct / 5) * 5))
+    session="$(printf '%s' "$input" | jq -r '.session_id // "unknown"' 2>/dev/null)"
+    mark_dir="${TMPDIR:-/tmp}/claude-window-fill"
+    mark="$mark_dir/$session.step"
+    mkdir -p "$mark_dir" 2>/dev/null
+    last="$(cat "$mark" 2>/dev/null)"
+    case "$last" in
+        '' | *[!0-9]*) last=0 ;;
+    esac
+    [ "$step" -gt "$last" ] || exit 0
+    printf '%s' "$step" > "$mark" 2>/dev/null
+
+    if [ "$pct" -ge "$stop_pct" ]; then
+        text="ЗАПОЛНЕНИЕ ОКНА ${pct}% (${fill_k}k из ${window_k}k) — заход закрывается сейчас. Всё, кроме записи хода работы, передачи и команд поставки, уже отбивается."
+    else
+        text="ЗАПОЛНЕНИЕ ОКНА ${pct}% (${fill_k}k из ${window_k}k). Пора выбирать точку остановки: с ${stop_pct}% останется только закрыть заход. Доведи текущий шаг до состояния, с которого следующий заход продолжит, перепиши «Где стоим» в ходе работы, напиши передачу и отдай владельцу путь к ней — паттерн task-flow-handoff."
+    fi
+
+    jq -n --arg t "$text" \
+        '{hookSpecificOutput:{hookEventName:"PostToolUse",additionalContext:$t}}' 2>/dev/null
+    exit 0
+fi
+
+# --- второй порог: работа отбивается, закрытие захода пропускается ------------------------
+
+[ "$event" = "PreToolUse" ] || exit 0
+[ "$pct" -ge "$stop_pct" ] || exit 0
+
+tool="$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null)"
+path="$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null)"
+cmd="$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null)"
+
+allowed=0
+case "$tool" in
+    # Разговор с владельцем и чтение того, что правится при закрытии.
+    AskUserQuestion | TodoWrite | Read | SendUserFile)
+        allowed=1
+        ;;
+    Edit | Write | MultiEdit | mcp__webstorm__create_new_file)
+        # Ход работы и передача. Остальное — работа, а её заход уже не начинает.
+        case "$path" in
+            "$tasks_dir"/* | */"$tasks_dir"/* | "$handoff_dir"/* | */"$handoff_dir"/* | */scratchpad/*) allowed=1 ;;
+        esac
+        ;;
+    Bash | mcp__webstorm__execute_terminal_command)
+        # Поставка и сверки: коммит, пуш, отчёт, колонка задачи, состояние дерева. Список
+        # дописывается профилем дерева — клиент хостинга и имена команд у каждого свои.
+        if command -v rt_handoff_allowed_cmd >/dev/null 2>&1 && rt_handoff_allowed_cmd "$cmd"; then
+            allowed=1
+        fi
+        ;;
+esac
+
+[ "$allowed" -eq 1 ] && exit 0
+
+reason="BLOCKED by window-fill-guard: заполнение окна ${pct}% (${fill_k}k из ${window_k}k), порог остановки ${stop_pct}%. Заход дальше не работает — он закрывается.
+
+Что осталось сделать этим заходом:
+1. Перепиши раздел «Где стоим» в ходе работы и добавь запись захода — что сделано, чем подтверждено, что не вышло.
+2. Закоммить проверенное: незакоммиченное не переживёт перерыв.
+3. Напиши передачу в ${handoff_dir}/ и отдай владельцу путь к ней — что в неё входит, говорит паттерн task-flow-handoff.
+
+Пропускаются при этом: правка ${tasks_dir}/**, запись передачи, команды поставки и сверки, чтение файлов и вопрос владельцу."
+
+jq -n --arg r "$reason" \
+    '{hookSpecificOutput:{hookEventName:"PreToolUse",permissionDecision:"deny",permissionDecisionReason:$r}}' 2>/dev/null \
+    || printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"window-fill-guard: окно заполнено, заход закрывается передачей."}}\n'
+
+exit 0

package/assets/laws/code-structure.md

@@ -20,3 +20,13 @@
   причина названа рядом.
 - **Отметка об устаревании — повод убрать, а не повод оставить.** Устаревшее объявление,
   которое молча продолжает работать, переживает того, кто его пометил.
+
+## Открытые вопросы
+
+- **Q-CS-3 — имя файла без обещания рода не судится ничем.** Проверка спрашивает файл, чьё имя
+  род называет; имя из одних слов о содержимом не говорит вовсе, и назвать род обязанным можно
+  только решением о продукте.
+- **Q-CS-4 — одноступенчатое приведение остаётся непроверенным.** Запрещено обходить сверку
+  через промежуточное «неизвестно», а обычное приведение принято: часть его обязательна, и
+  запрет отбивал бы её вместе с остальным. Решение изменит, появится ли требование к причине у
+  каждого оставшегося.

package/assets/laws/delivery.md

@@ -16,7 +16,14 @@
   которая в одну ветку не влезает, делится на задачи до того, как ветка заводится. Признак
   деления — раздельный откат, а не объём: числа файлов, строк или коммитов, за которым работа
   становится двумя задачами, нет. Правка одного рода остаётся одной задачей, сколько бы файлов
-  она ни задела.
+  она ни задела. Объём захода исполнителя признаком деления не является тоже: он говорит, какого
+  размера задачу стоит заводить среди тех, что делятся законно, и не даёт делить то, что
+  откатывается только вместе.
+- **Правка самой поставки проверяется её прогоном, а не рассуждением.** Проверить её иначе
+  нечем: она исполняется только там, где выкатывает, и в среде, которой на месте работы нет — с
+  чужими правами, чужим хранилищем ключей и чужой сетью. «Проверю после слияния» решением
+  исполнителя не бывает: за этими словами стоит выкатка, которой уже не будет, если правка
+  окажется неверной. Отложить проверку может только владелец, и он говорит это словами.
 - **Две задачи, которые чинятся одной правкой, — одна задача.** Вторая стирается вместе со
   своим номером, а то, чего в первой не было, дописывается в неё до этого. Две строки об
   одной работе хуже дыры в нумерации: по ним потом не понять, что сделано, а что нет. Слить

package/assets/laws/project-documentation.md

@@ -19,6 +19,10 @@
   символ ничего не исполняет, а проверка на нём остаётся зелёной.
 - **Путь, названный в документе, существует.** Ссылка на переехавший файл читается как
   действующее указание, и следующий читатель заводит снятое заново.
+- **Указатель каталога перечисляет всё, что в каталоге лежит.** Записи, которой в указателе нет,
+  для читателя не существует: он ищет по указателю, а не обходом каталога, и заводит разбор
+  заново. Это обратная сторона предыдущей статьи — не только путь из текста ведёт в файл, но и
+  файл назван в тексте, по которому его ищут.
 - **Документ, разошедшийся с приложением, правится тогда же, когда замечено расхождение.**
   Отложенная правка не случается: расхождение перестаёт быть заметным на следующий день.
 - **Расхождение чинится в той стороне, которая неправа, и это не всегда документ.**
@@ -29,7 +33,17 @@
   — это намерение, а не свойство приложения: сверить его не с чем, и оно проходит любую
   проверку. Машине это не поручить: открытый вопрос пишется теми же словами, что и обещание,
   и проверка отбивала бы оба.
+- **Документ утверждает о состоявшемся, а не о том, что должно сработать.** Лечение,
+  записанное готовым до того, как его прогнали, дороже отсутствия записи: следующий читатель
+  берёт его за проверенное — и берёт в тот день, когда лечение понадобилось, а времени на
+  разбор нет. Непрогнанное либо не пишется вовсе, либо названо непроверенным тем же
+  предложением.
 - **Число в тексте пересчитывается тем же изменением, которым пишется, и за этим тоже следит
   автор.** Устаревшее число выглядит так же, как свежее, а машине их не различить: дата,
   версия и номер — такие же числа, и проверка, которая знает один способ записи, на другом
   ошибается молча.
+- **Отказ от слова распространяется на всё, что уже прочитано снаружи, а не только на файлы.**
+  Название работы, её описание и запись о правке живут вне дерева: поиск по файлам их не
+  видит, проверки текстов на них не смотрят, и отказ выглядит сделанным ровно до того, как
+  читатель наткнётся на снятое слово в заголовке. Читатель при этом заключает, что от слова
+  не отказывались вовсе.

package/assets/laws/verifiability.md

@@ -21,6 +21,10 @@
   выкинутый сценарий: без этого он пропадает молча.
 - **Работающее приложение проверяется там, где его видит пользователь.** Отладочный режим
   ведёт себя иначе рабочего, и проверка в нём подтверждает не то, что будет у пользователя.
+- **Перед отправкой правка проверяется тем же набором, что и конвейер, и теми же командами.**
+  Набор, собранный по изменённым файлам, пропускает то, до чего правка дошла связями: проверка
+  зелёная, а конвейер красный. Что проверять, считает инструмент от той же базы, а не память
+  автора.
 - **Проверка признака окружения относится только к тому пути запуска, на котором она
   сделана.** Пути, которыми одно и то же приложение поднимается, задают признаки по-разному,
   и подтверждённое на одном из них на остальных неверно — а выглядит проверенным целиком.
@@ -30,6 +34,15 @@
   наступило.** Часть запросов выполняется наполовину, и об отклонённой части в ответе ничего
   нет: по коду возврата такой вызов не отличить от исполненного. Поэтому результат читают
   отдельным запросом, и в отчёт идёт то, что прочитали, а не то, что заказывали.
+- **Служба считается поднятой, когда она выполнила задание, а не когда сообщила о
+  готовности.** Сообщение о готовности говорит лишь, что служба себя объявила: та, которой не
+  досталось ни одного задания, выглядит в нём точно так же, как работающая. Проверяются обе
+  стороны связи — что заказчик выбирает именно её и что задание через неё прошло.
+- **Причина отказа, на которой строится решение, подтверждается измерением, а не
+  правдоподобием.** Объяснение, пришедшее первым, объясняет наблюдаемое не хуже верного:
+  свойство среды и собственный промах выглядят в отказе одинаково, и разводит их только замер,
+  поставленный так, чтобы одно из двух не прошло. Решение, выведенное из неподтверждённой
+  причины, лечит не то — и стоит отката всей работы, а не одной правки.
 - **Если инструмент проверки запрещает приём, которым здесь пользуются постоянно, его правило
   выключают в настройке инструмента, а не обходят в каждом месте.** Обход приходится повторять
   столько раз, сколько таких мест, и ни в одном из них не написано, зачем он: со стороны это

package/assets/laws/work-conduct.md

@@ -15,6 +15,10 @@
   всего.
 - **Владельцу не задаётся вопрос, ответ на который уже записан.** Записанное читают до
   разговора, а не вместо ответа: вопрос о том, что уже решено, обесценивает и остальные.
+- **Решение, однажды записанное, действует, пока его не отменили, и читается до того, как
+  принимается заново.** Отменённое решение следа в работе не оставляет — по результату не
+  видно ни того, что его принимали, ни того, что от него отказались. Принятое заново оно
+  расходится с прежним молча и стоит той же работы второй раз.
 - **Понимание записано там, где идёт работа.** Оставленное в переписке живёт у одного
   участника и до следующего дня; работу продолжает тот, у кого этой переписки нет.
 - **Сказанное владельцем записывается его словами и задним числом не переписывается.**
@@ -22,9 +26,21 @@
 - **Договорённость о том, как продукт себя ведёт, записана раньше кода, который её
   исполняет.** Записанная после, она пишется по коду и повторяет его ошибки: разойтись ей
   уже не с чем, а значит она ничего не проверяет.
+- **Описание приведено к сделанному прежде, чем работа закрыта.** Договорённость пишется до
+  кода и описывает замысел, а к концу работы приложение отличается и от замысла тоже.
+  Расхождение, отложенное на потом, не находится: назавтра оно уже незаметно, а описание
+  продолжают читать как верное.
 - **Состояние незаконченной работы восстанавливается без участия владельца.** Иначе каждый
   перерыв стоит ему пересказа, а очередь работ показывает начатое и не говорит, что внутри
   него сделано.
+- **Заход исполнителя конечен, и его конец не совпадает с концом работы.** Место, где
+  исполнитель помнит ход работы, ограничено; заполнив его, он теряет не последнее, а всё
+  сразу. Заход, доведённый до логической точки заранее, стоит одной записи; оборванный на
+  середине — целого захода на восстановление.
+- **Прерванная работа передаётся следующему заходу готовым текстом, а не пересказом
+  владельца.** Владелец знает, что работа не кончена, но не знает, где именно она стоит;
+  пересказ он даёт по своей памяти, а не по ходу работы, и следующий заход начинает с чужой
+  картины.
 - **Замысел и ход работы — разные записи.** Замысел — то, с чем сверяют результат при
   приёмке; правленный по ходу, он перестаёт отличаться от отчёта, и приёмке сверять нечего.
 - **Сделанное отмечается в одном месте.** Две записи об одном разъезжаются молча, и после
@@ -39,6 +55,9 @@
   нетронутое, и второй заход начинает его заново.
 - **Записи о законченной работе не лежат среди записей о текущей.** Закрытое, лежащее рядом
   с действующим, читается как действующее — тем убедительнее, чем оно старше.
+- **Законченная работа убирает за собой до того, как войдёт в общее дерево.** Потом за
+  оставленным уже никто не следит: работа перешла к следующей задаче, а правки, которой это
+  убрали бы заодно, больше нет.
 - **Достаточность понимания судит тот, кто просил.** Машине видно наличие записи, но не то,
   что в ней закрыты все пробелы: запись из одной строки проходит так же, как разбор на сто.
   Признак достаточности, выведенный из объёма или числа вопросов, сам становится целью —

package/assets/patterns/git-workflow-commit.github.md

@@ -305,6 +305,10 @@ in-review`, — и `npm run check:board` прогоняется ещё раз:
   `git commit --amend` при этом уносит в коммит всё, что осталось в индексе, — так в коммит
   уехало удаление файла, принадлежавшее соседней ветке. Состав коммита читается
   `git show --stat` сразу после него, а не на разборе PR.
+- Состав индекса читается `git diff --cached --stat` **до** коммита, а не только `git show --stat`
+  после него. Команды дерева кладут файлы в индекс сами: `npm run task:new` добавляет папку
+  задачи, и вместе с ней уезжает всё, что лежало рядом, — так в индексе оказался временный
+  каталог диагностики.
 - `gh project` с `--owner` отвечает `unknown owner type`: владелец борды — другая учётная
   запись, и правка идёт только через GraphQL.
 - Заведённый тикет на борду сама она не забирает: репозиторий с ней не связан, и добавление

package/assets/patterns/spec-driven-domain.md

@@ -23,11 +23,16 @@ docs/specs/<домен>/
     spec.md              — как домен работает
     implementation.md    — таблица «правило → файл:символ»
     scenarios.md         — сценарии SC-<ПРЕФИКС>-<НОМЕР>
+    <поддомен>/          — свой spec.md, implementation.md и scenarios.md
     proposed/<фича>/     — только то, чего ещё нет
 ```
 
 Шаблон — `docs/specs/_template/spec.md`, указатель с префиксами — `docs/specs/README.md`.
 
+Поддомен спрашивается наравне с доменом: те же обязательные разделы, тот же компаньон рядом,
+та же связь сценариев с тестами. Домен, у которого половина поддоменов описана, а половина
+заведена пустыми каталогами, зелёным не бывает.
+
 ## Обязательные разделы
 
 `## Зачем` · `## Терминология` с подразделом `### Как это называется в интерфейсе` ·
@@ -84,6 +89,18 @@ docs/specs/<домен>/
 `Не покрыто: <причина>`, сценарий с неполным тестом — `Покрытие: частичное — <чего не
 хватает>`.
 
+Номер в идентификаторе живёт так:
+
+| Что случилось           | Что делается с номером                                                                               |
+| ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| сценарий добавили       | берётся следующий свободный — наибольший выданный в домене плюс один, а не дырка в середине          |
+| обещание изменили       | номер тот же, заголовок теста правится тем же коммитом                                               |
+| сценарий удалили        | номер остаётся пустым и новому сценарию не отдаётся; тест удаляется вместе со сценарием              |
+| номера захотелось сжать | не пересчитываются: связь с тестами держит только номер, а прогон остаётся зелёным при обеих правках |
+
+Номер записывается так же, как у соседей в этом же файле: сверка ищет его шаблоном, и номер,
+записанный иначе, не совпадёт ни в спеке, ни в заголовке теста.
+
 ## Порядок работы
 
 1. Задача заводится сценариями: что станет верно, когда работа закончится.
@@ -94,6 +111,14 @@ docs/specs/<домен>/
 
 ## Частые промахи
 
+- Выросший домен делят на новые домены, а не на поддомены: новый домен приходится заводить в
+  указателе, сверять с кодом отдельно и объяснять, чем он соседу не поддомен, — а поддомен
+  остаётся в своём домене и наследует его контракт. Соседний домен заводится только тогда,
+  когда предмет живёт своей сущностью. Границу проводит владелец: деление переписывает номера
+  во всех заголовках тестов домена, и вернуть его назад тем же движением нельзя.
+- Счётчик правил или сценариев в указателе доменов: он пересчитывается при каждой правке
+  любого спека, и через год большая часть таких чисел молча описывает позавчерашний спек.
+  Указатель держит домен, префикс и одну строку «о чём».
 - `tasks.md` в спеке: шаги — артефакт сессии, им место в ветке или в описании PR.
 - Скопированная из контракта таблица полей: источник — `libs/common/proto/proto/<область>/v1/`,
   и компилируется из двух только одна.
@@ -102,6 +127,16 @@ docs/specs/<домен>/
 - Место, где правило исполняется, внутри текста правила: оно меняется при первом рефакторинге,
   и для него заведён `implementation.md`.
 - Пометка «Не покрыто» при существующем тесте — отказ: долг закрыли, а отметку не сняли.
+- Пометка «Не покрыто» читается дословно и с начала строки. Любое слово между ней и двоеточием
+  — «Не покрыто, и прогоном не покрывается вовсе: …» — и сценарий считается непомеченным вовсе,
+  а причина, ради которой пометку и писали, до отчёта не доезжает.
 - Закон, названный в тексте, но забытый в строке `**Законы:**`: по закону тогда не узнать,
   какие домены на нём стоят.
 - Правка `.proto` без спеков задетых доменов: `docs-guard` отбивает такой коммит.
+- **Выросший домен делится на поддомены, а не на новые домены.** Новый домен пришлось бы
+  заводить в указателе, сверять с кодом отдельно и объяснять, чем он соседу не поддомен;
+  поддомен остаётся в своём домене и наследует его контракт. Соседний домен заводится только
+  тогда, когда предмет живёт своей сущностью.
+- **Границу между доменами проводит владелец, а не автор очередной правки.** Автор видит свою
+  правку, а не то, чем предмет обрастёт: домен, заведённый по ходу дела, через месяц оказывается
+  половиной соседнего, и разводить их приходится вместе с номерами сценариев.