# Tasks Как строить — `design.md` (дальше «решение N»). Что должно получиться — дельты `specs/graceful-shutdown`, `specs/student-tests` и `specs/load-benchmark`. Номера коммитов — таблица решения 14. **Правила.** - **Правила слоёв.** Перед первым файлом слоя — Read его правила (и одного файла из каталога, чтобы правило подгрузилось): | Что правим | Правила | |---|---| | `bench/` | `.claude/rules/bench.md` | | `student-tests/` | `student-tests.md`, `api-contract.md` | | `src/infra/`, `src/main.py`, `src/__main__.py` | `infra.md`, `logging.md`, `run-modes.md`, `api-layer.md`, `docker.md` | | `scripts/rolling-update.sh` | `balancer.md` | | `.claude/skills/run-mtusi-messenger/driver.py` | `SKILL.md` того же каталога | - **Только Edit и Write.** Файлы меняются только ими: не sed, не heredoc, не `python -c` (глобальное правило пользователя). Перед правкой — Read файла. Запускать `uv run python -c …` и `python3 -c …` для проверок можно. - **Коммиты** — без подтверждения (бриф основной сессии). Английский conventional style, сообщения — таблица решения 14, последняя строка `Co-Authored-By: Claude Opus 5.5 `. Push, checkout, reset, stash, rebase нельзя; `git revert` в задаче 3.6 — можно. - **Стенды.** Удалять и пересоздавать можно `mtusi-lab3` (рабочий), `mtusi-bench` и `mtusi-lab3-failures`. Чужие проекты (`mtusi-lab2` и другие) не трогать. - **Упавший тест или прогон** — сначала разбор и названная причина, потом правка (AGENTS.md). Правка кода — новый commit и повтор проверки. - **Журнал этапа** — `/fix-known-issues/journal.md` (scratchpad сессии apply): хэши, ключевые строки выводов, заметки для «Найдено в apply». Отметки задач до 8.8 тоже ведутся там: паспорт меток `bench/` пишет `git.dirty`, и перед каждым `make bench_*` `git status --porcelain` должен быть пуст. В файлы change отметки переносятся в 8.8. - **`REPORT.md` может править основная сессия.** Перед каждой правкой — свежий Read. Чужие изменения не откатывать и от своего имени не коммитить: спросить основную сессию. - **Долгие команды** — всё дольше пары минут — фоном, журнал в `/fix-known-issues/<имя>.log`: ```sh nohup make <цель> > /fix-known-issues/<имя>.log 2>&1 & ``` Ожидание — циклом (`until ! pgrep -f "[b]ench/run.py" >/dev/null; do sleep 15; done`, Bash с `run_in_background` или Monitor), не дольше 30 мин на вызов. Ни один вызов инструмента не должен упереться в 10 минут. - **Проверка хоста** — перед каждым прогоном `bench/` (3.4, 3.5, 3.7, 7.8) и перед замерами `stop-at-start` (5.2, 5.9). Вывод — в журнал: - `pmset -g batt | head -1` — `AC Power`; - `memory_pressure | tail -1` — давления нет, свободной памяти хватает на ВМ 7,7 GiB (ориентир прежних замеров — 50 % и больше); - для `bench/`: `make stop`, затем `docker ps --format '{{.Names}}'` — пусто; - `LC_ALL=C sysctl -n vm.loadavg` — второе число (5 мин) < 8; - `pgrep -x zoom.us` — пусто; - `vm_stat | grep Swapouts` — до прогона и после. Плохо хоть одно — прогон не запускать: остановиться и вернуть отчёт основной сессии с выводом команды. - **Секреты.** В evidence и журнале нет токенов, паролей, хэшей целиком, `.env` и абсолютных путей домашнего каталога (`evidence/README.md`). - **Уведомления в Telegram** — только если их поручает бриф apply, через скилл `telegram-send`. ## 1. Подготовка - [ ] 1.1 Исходное состояние: - `git status --porcelain` пуст; - `git log --oneline -1` — commit `docs: propose fix-known-issues change`. Его хэш — `BASE` в журнале; - `docker compose ps` — пять контейнеров `mtusi-lab3` `healthy`, `make lb_stats` — обе реплики `UP`. Иначе — `make run_docker`. - [ ] 1.2 Read правил из таблицы «Правила слоёв» и по одному файлу из каждого затрагиваемого каталога: `bench/run.py`, `student-tests/run_failures.py`, `src/main.py`, `src/infra/logger.py`, `scripts/rolling-update.sh`, `.claude/skills/run-mtusi-messenger/driver.py`. Проверка: список прочитанного — в журнале. ## 2. Паспорт метки — `swapouts_delta` (запись 5, решение 13) - [ ] 2.1 `bench/run.py`: - функция `swapouts_delta(start, end) -> int | None` рядом со `swap_warning`, с докстрингом: `None`, если одного счётчика нет; иначе разность, в том числе 0; - `swap_warning` считает через неё, тексты предупреждений прежние; - конец `main()` пишет `meta["host_state"]["swapouts_delta"]`, когда значение не `None`; - код ячеек серий (`host_swapouts`) не трогать. Проверка: `git diff --stat` — только `bench/run.py`. - [ ] 2.2 Самопроверка, вывод — в журнал: ```sh uv run python -c "import sys; sys.path.insert(0, 'bench'); import run; d, w = run.swapouts_delta, run.swap_warning; assert d({'swapouts': 0}, {'swapouts': 0}) == 0; assert d({'swapouts': None}, {'swapouts': 3}) is None; assert d({'swapouts': 5}, {'swapouts': None}) is None; assert d({'swapouts': 5}, {'swapouts': 9}) == 4; assert w({'swapouts': 0}, {'swapouts': 0}) is None; assert w({'swapouts': 5}, {'swapouts': 9}) == 'host swapped out 4 pages during the run: rerun'; print('swapouts ok')" ``` Ожидается `swapouts ok`. Затем `make lint` — код 0, других файлов он не меняет. - [ ] 2.3 Commit 1. Проверка: `git status --porcelain` пуст. ## 3. События фазы `failover` — поток (запись 3, решения 9, 10) - [ ] 3.1 `bench/run.py` (решение 9): - метод `Stand.container_events(container, path)` — поток `docker events` по контейнеру в файл, тот же фильтр и формат, что у прежнего `Stand.events`; докстринг — почему поток (буфер демона, 256 событий); - `run_phase`: поток — в `work_dir/<фаза>-events.log`, запуск после выбора цели и до `k6_console`, остановка `terminate` + `wait` после `wait_ready` после фазы, в `finally`. События — `failover.parse_events` этого файла, выбор действия и возврата прежний; - прежний `Stand.events` удалить. Проверка: - `grep -n "def events\|stand.events(" bench/run.py` — пусто; - `grep -n "container_events" bench/run.py` — определение и вызов; - сообщение `docker events of … not found` осталось (сценарий «Событие не получено»); - `uv run python bench/scaling.py --selftest` и `uv run python bench/resources.py --selftest` — `selftest ok`; - `make lint` — код 0. - [ ] 3.2 Commit 2. Проверка: дерево чистое, хэш — в журнал. - [ ] 3.3 Временная сверка (решение 10): - в `bench/run.py` — метод запроса к буферу демона: копия прежнего `Stand.events` под именем `events_from_buffer`; - в `run_phase` после событий из потока — тот же разбор по буферу за окно `started - 5` … `ended + 1`: - TimeNano действия и возврата равны — `self.say` «cross-check: stream = buffer», оба момента; - в буфере их нет — «cross-check: buffer lost the events»; - различаются — `BenchError`. `make lint`, commit 3. Хэш — в журнал. - [ ] 3.4 Прогон 1 без помех: проверка хоста (с `make stop`), затем `nohup make bench_failover_quick > /fix-known-issues/failover-cross.log 2>&1 &`, ожидание. Проверка: - код 0, 4 фазы; - в журнале 4 строки «cross-check: stream = buffer»; - `meta.json` метки `evidence/failover/quick-failover-*` (последней): - `status` `complete`, `git.dirty` `false`, `git.commit` = commit 3; - `host_state.swapouts_delta` есть и равен `end.swapouts − start.swapouts`. Его нет — только если `start.swapouts` равен `null`. Чтение — `python3 -c` с `json.load`. Сбой — разбор. - [ ] 3.5 Прогон 2 под шумом `docker exec`. Проверка хоста, затем: ```sh S=/fix-known-issues; rm -f $S/noise.stop nohup sh -c 'n=0; s=$(date +%s); while [ ! -f "$1" ]; do if docker exec mtusi-bench-valkey true >/dev/null 2>&1; then n=$((n + 1)); else sleep 0.5; fi; done; echo "noise-execs=$n seconds=$(( $(date +%s) - s ))"' sh $S/noise.stop > $S/noise.log 2>&1 & nohup make bench_failover_quick > $S/failover-noise.log 2>&1 & ``` После конца `run.py` — `touch $S/noise.stop`, затем `cat $S/noise.log`. Проверка: - код 0, 4 фазы, строк «docker events … not found» нет; - хотя бы в одной фазе «cross-check: buffer lost the events»; - в журнал — частота шума (execs за секунды) и какие фазы потеряли события в буфере. Ни одна фаза не потеряла — шума мало: повтор один раз с двумя такими циклами. Снова нет — записать как результат и идти дальше. - [ ] 3.6 Откат сверки: `git revert --no-commit `, затем `git commit`, сообщение commit 4 с телом «This reverts commit <хэш>.» и строкой `Co-Authored-By`. Проверка: `git diff HEAD -- bench` пуст. - [ ] 3.7 Итоговый прогон на окончательном коде: проверка хоста, `make bench_failover_quick` (фоном, журнал `failover-final.log`). Проверка: - код 0, 4 фазы, строк «cross-check» нет; - `meta.json`: `git.commit` = commit 4, `git.dirty` `false`, `swapouts_delta` — как в 3.4. Затем рабочий стенд снова: `make run_docker`, `make lb_stats` — обе реплики `UP`. ## 4. PostgreSQL стенда отказов (запись 4, решения 11, 12) - [ ] 4.1 `student-tests/run_failures.py` (решение 12): - константа признаков аварии; - функция чтения журнала: `dc(project, "logs", "--no-log-prefix", "postgres", quiet=True)`; - сводка `postgres log: N lines, crash markers M; "too many clients" X, "administrator command" Y`; - при M > 0 — строки признаков (не больше 20) и `results["postgres"] = 1`; - вызов после pytest и до уборки, только если pytest запускался; - строка в докстринге модуля. `make lint`, commit 5. - [ ] 4.2 Красный прогон, то есть воспроизведение дефекта на закоммиченном коде (сценарий «PostgreSQL перезапустился аварийно»): `nohup make failure_checks > /fix-known-issues/failure-red.log 2>&1 &`, ожидание (~70 с). Ожидается: - 17 passed; - сводка журнала с `crash markers` > 0, среди строк — `untracked child process … exited with exit code 2` и `reinitializing`; - `results` содержит `'postgres': 1`, код выхода не 0; - стенд отказов удалён: `docker ps -a --filter label=com.docker.compose.project=mtusi-lab3-failures -q` пусто. Не воспроизвелось — повтор `make failure_checks FAULT_ARGS='-k connection_limit'` до двух раз. Нет и тогда — остановиться, разобрать и вернуть отчёт основной сессии; `init: true` вслепую не коммитить. - [ ] 4.3 Исправление (решение 11): - `student-tests/failures.compose.yml`: `init: true` у `postgres`; в шапке — зачем (сироты `psql` из `fill-connections` подбирает init, а не postmaster); - `student-tests/fault_hook.py`: комментарий у `FILL_SH` про сирот и init стенда. Код hook не меняется. `make lint`, commit 6. - [ ] 4.4 Зелёные прогоны (сценарий «Заполнение и освобождение слотов»): `make failure_checks` два раза. До и после — `StartedAt` контейнеров `mtusi-lab3` (`docker inspect`). В каждом прогоне: - код 0, 17 passed; - сводка `crash markers 0`, а «too many clients» и «administrator command» > 0: заполнение и освобождение правда были; - `results: {'fault': 0, 'postgres': 0}`, стенд отказов удалён. Во время одного прогона, пока идёт pytest: `docker inspect -f '{{.HostConfig.Init}}' mtusi-lab3-failures-postgres-1` → `true`. `StartedAt` рабочего стенда не изменился. ## 5. Ранний обработчик сигналов (запись 2, решения 3–8) - [ ] 5.1 Команда `stop-at-start` в `driver.py` (решение 8): аргументы, контейнеры по метке, поток событий, классы попыток, «кто остановил», PASS, уборка в `finally`. Плюс строка в докстринге драйвера. Проверка: - `/usr/bin/python3 -m py_compile .claude/skills/run-mtusi-messenger/driver.py` — синтаксис 3.9; - `python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --help`; - `make lint` — код 0. Commit 7. - [ ] 5.2 «До» (сценарии `graceful-shutdown` на прежнем коде). Образ: `git archive --format=tar HEAD | docker build -t mtusi-messenger:stop-before -` — HEAD это commit 7, код приложения как в `BASE`. ID образа — в журнал. Проверка хоста, затем `python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --image mtusi-messenger:stop-before > /fix-known-issues/stop-before.log`. Ожидается: - код 1; - попытки `import`: `docker stop` ≈ 10 с, код 137, остановки в журнале нет, а «Uvicorn running on» появился уже после сигнала — дефект воспроизведён; - попытки `running` и `server-start`: код 0, остановил `uvicorn`. - [ ] 5.3 Код (решения 3–5): - новый `src/infra/early_stop.py`: только stdlib, `install()`, `disarm()`, обработчик — запись по решению 5 и `os._exit(0)` в `finally`; докстринг со ссылкой на design; - `src/__main__.py` — по решению 3, импорты внутри `if __name__ == "__main__"`; - `src/main.py`: `early_stop.disarm()` — первая строка `lifespan`, комментарий зачем. Проверка: - `grep -nE "^(import|from) " src/infra/early_stop.py` — только stdlib; - `.venv/bin/python -c "import src.infra.early_stop"` — код 0; - `make lint` — код 0. - [ ] 5.4 `scripts/rolling-update.sh`, `remove_new` (решение 7): - слот есть → `maint` → `docker stop --timeout 10` с временем и кодом выхода → `docker rm -f` → адрес ушёл → `ready`; - слота нет → `docker rm -f`; - строка `removed new …` в формате решения 7; - комментарий без ссылки на `KNOWN_ISSUES.md`. Проверка: `sh -n scripts/rolling-update.sh`; `git diff` — только `remove_new` и комментарии. - [ ] 5.5 `make lint`, `make check`, commit 8. Хэш — в журнал. - [ ] 5.6 Консоль на commit 8 (решение 6, сценарий «Ctrl+C в консоли во время старта»), порт 18089 свободен (`lsof -nP -iTCP:18089 -sTCP:LISTEN` пусто): - SIGTERM на импорте: ```sh APP__RUN_MODE=console APP__PORT=18089 .venv/bin/python -m src > /fix-known-issues/console-term.log 2>&1 & pid=$!; sleep 0.3; kill -TERM $pid; wait $pid; echo "exit=$?" ``` Ожидается `exit=0`. В журнале одна строка JSON «Stopped API before startup» с `signal` `SIGTERM`, `level` `info`, `timestamp`, `instance_id`, traceback нет. - То же с `kill -INT` — `exit=0`, `signal` `SIGINT`. - После готовности: тот же запуск, ожидание `curl -sf http://127.0.0.1:18089/health/live`, затем `kill -TERM $pid` и `wait`. Ожидается `exit=0`: «Shutting down», «Stopped API», «Finished server process», записи «before startup» нет. - Reload (`D=.claude/skills/run-mtusi-messenger/driver.py`): `python3 $D start` (порт 18080), `touch src/main.py`, через 3 с в `/tmp/mtusi-api-18080.log` — «Reloading», `python3 $D status` — `ready: True`, `python3 $D stop`. `git status --porcelain` пуст. - [ ] 5.7 Новый код на рабочий стенд без простоя: - до замены — ID и `.Image` реплик (`docker compose ps -q api`, `docker inspect -f '{{.Image}}'`); - `python3 tests/load.py --duration 45 --concurrency 4 > /fix-known-issues/load-rollout.log 2>&1 &`, затем `make rolling_update > /fix-known-issues/rollout.log 2>&1`, затем ожидание нагрузки. Проверка: - код скрипта 0, две строки `removed old … (stop Ns, exit 0)`; - `failed_requests` 0 в отчёте `tests/load.py`; - `make lb_stats` — две реплики `UP`; - реплики с новыми ID на одном новом `.Image`; - в журнале новых реплик — обычный старт. - [ ] 5.8 Ветка сбоя `rolling-update.sh` (решение 7): - `ROLLOUT_READY_TIMEOUT=1 make rolling_update`: код 1, строки `removing new replica … that is not ready` и `removed new … (no slot: docker rm -f)` или `(slot api-N: stop Ns, exit 0)`; - `ROLLOUT_READY_TIMEOUT=2 make rolling_update` — ради пути со слотом. Записать, какой путь сработал. Если замена успела завершиться (код 0) — это тоже результат; - после каждого запуска: `make lb_stats` — две реплики `UP`; `docker compose exec -T haproxy bash -c 'exec 3<>/dev/tcp/127.0.0.1/9999 && echo "show servers state api" >&3 && cat <&3'` — у слотов `srv_admin_state` 0 или 32, без флагов 1 и 8. - [ ] 5.9 «После». Проверка хоста, затем `python3 .claude/skills/run-mtusi-messenger/driver.py stop-at-start --image mtusi-messenger:lab3 > /fix-known-issues/stop-after.log`. ID образа равен `.Image` реплик рабочего стенда. Ожидается: - код 0, PASS; - попытки `import`: остановил `early`, `docker stop` ≤ 1 с, код 0; - хотя бы одна `server-start`: остановил `uvicorn`, ≤ 1 с, код 0. Ни одной — повтор с `--server-start 10`; - `running`: остановил `uvicorn`, код 0. - [ ] 5.10 Регрессия консоли: `lsof -nP -iTCP:18080 -sTCP:LISTEN` пусто, затем `python3 .claude/skills/run-mtusi-messenger/driver.py all`. Ожидается: `FAILED: none` у `flow`, `PASS` у smoke, все тесты прошли, тесты реплик пропущены с причиной, код 0. - [ ] 5.11 Уборка: `docker image rm mtusi-messenger:stop-before`; `docker ps -a --filter label=mtusi.stop-at-start -q` пусто. ## 6. Доказательства исключений сверки (запись 1, решения 1, 2) - [ ] 6.1 Команды `cache-check` и `auth-storage` в `driver.py` (решение 1), строки в докстринге. Проверка: - `/usr/bin/python3 -m py_compile .claude/skills/run-mtusi-messenger/driver.py`; - `make lint` — код 0; - пробный запуск обеих против рабочего стенда (`--port 8080`): код 0, в выводе нет токена, пароля и хэшей. Commit 9. - [ ] 6.2 `make test_isolated > /fix-known-issues/test-isolated.log 2>&1` при работающем рабочем стенде. Ожидается код 0, 4 теста реплик пропущены с причиной. Сразу после — 6.3: ключи тестового прогона нужны в Valkey. - [ ] 6.3 Снятие доказательств, ничего другого на стенде не идёт: - `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 cache-check > /fix-known-issues/cache-check.log`. Код 0. Ожидается (решение 1, шаги 5–8): чтений `chats` 1, hits +49, промахов +1; 60 ответов 200 (50 в окне счётчиков, 10 — для срока); TTL ≤ настроенного и чтениями не продлевается; ≥ 2 `X-Instance-Id`; ключи обоих префиксов > 0; - `python3 .claude/skills/run-mtusi-messenger/driver.py --port 8080 auth-storage > /fix-known-issues/auth-storage.log`. Код 0, факты решения 1. Проверка секретов: `grep -nE '/Users/|Bearer |\$argon2id\$[^ ]*\$[A-Za-z0-9+/]{8,}'` по обоим журналам — пусто. - [ ] 6.4 Сверка ссылок (решение 2): - `missing_evidence` в `student-tests/spec_coverage.py`; - два теста в `student-tests/test_coverage.py`; - тексты `check` пяти исключений называют команды. `make lint`, commit 10. Красная проверка на нём, до файлов доказательств (сценарий «Ссылка на отсутствующий файл»): `uv run pytest student-tests/test_coverage.py`. Тест на настоящих исключениях падает и называет пять сценариев и два пути, остальные проходят. Вывод — в журнал. - [ ] 6.5 `evidence/cache/hits.md` и `evidence/auth/passwords-and-tokens.md` по образцу файлов лабы 2: - шапка: спеки и сценарии, change, дата, commit (код команд — commit 9, приложения — commit 8), стенд (LB, две реплики, лимиты), хост, команда; - разделы с выводом команд; у `hits.md` — ещё строка `make test_isolated` (итог и время); - вывод. Проверка: `uv run pytest student-tests/test_coverage.py` — зелёный; grep секретов из 6.3 по обоим файлам — пусто. - [ ] 6.6 `make student_test` через LB — все прошли (на 2 больше, чем до change: 131 → 133), строка сверки покрытия с прежними числами (137 / 125 / 12). Commit 11: оба файла. ## 7. Регрессия на итоговом коде - [ ] 7.1 Статика: - `make lint`, `make check`, `make validate PYTHON=.venv/bin/python`; - `uv run python bench/scaling.py --selftest`, `uv run python bench/resources.py --selftest`, однострочник 2.2; - `sh -n scripts/rolling-update.sh`. Все — код 0. - [ ] 7.2 `make test` — `PASS`; `make instances` — `instances: 2`. - [ ] 7.3 `make student_test` через LB — все прошли, тесты реплик выполнены, строка сверки покрытия. - [ ] 7.4 `make test-persistence ACTION_SCRIPT=scripts/restart.sh` — `PASS`; `StartedAt` LB, реплик, PostgreSQL и Valkey до и после — новые, ID те же. - [ ] 7.5 `make test-failover` по `evidence/tests/clean-clone-final.md`, с `STOP_ONE_LOG`: - `stop` для одной реплики, `make replicas`, сдвиг очереди одним запросом, `stop` для другой; - `make replicas`, затем `STOP_MODE=kill`. Все `PASS`. ID остановленного контейнера = `TARGET_INSTANCE_ID`. Код выхода: `Exited (0)` у `stop`, `Exited (137)` у `kill`. В конце `make replicas`. - [ ] 7.6 `make test_isolated` — код 0. - [ ] 7.7 `make failure_checks` — код 0, сводка журнала PostgreSQL `crash markers 0`. - [ ] 7.8 Быстрые профили на итоговом коде. Проверка хоста (с `make stop`), дерево чистое, затем цепочкой фоном: ```sh nohup sh -c 'make bench_failover_quick && make bench_rollout_quick; echo "chain-exit=$?"' > /fix-known-issues/quick-final.log 2>&1 & ``` Проверка: - `chain-exit=0`; - `failover` — 4 фазы, сверка записей сошлась; - `rollout` — замена завершена, сверка сошлась, в `raw/rollout-script.log` строки `removed old … exit 0`; - у обеих меток `git.commit` = HEAD, `git.dirty` `false`, `host_state.swapouts_delta` есть. Затем `make run_docker`, `make lb_stats` — две реплики `UP`. ## 8. Документы и evidence проверок - [ ] 8.1 `evidence/failover/stop-at-start.md`: - шапка: сценарии `graceful-shutdown`, change, дата, commit «до» (7) и «после» (8), ID образов, лимиты (1 CPU / 512 МиБ, без сети), хост; - вывод `stop-at-start` «до» (5.2) и «после» (5.9), с пояснением классов; - строки `rolling-update.sh` ветки сбоя (5.8) и коды выхода старых реплик при замене (5.7); - вывод: что исправлено и что осталось — окно 0. - [ ] 8.2 `evidence/tests/fix-known-issues-checks.md`, в стиле `rolling-update-checks.md`. Шапка — change, даты, хэши коммитов 1–11, стенды, хост. Разделы: - самопроверка `swapouts_delta` (2.2); - сверка событий: прогон без помех (3.4), под шумом с частотой `docker exec` (3.5), итоговый (3.7), `swapouts_delta` в паспортах; - стенд отказов: красный (4.2) и зелёные (4.4) прогоны со сводкой журнала, `HostConfig.Init`, `StartedAt` рабочего стенда; - консоль (5.6, 5.10); - замена под нагрузкой (5.7); - красная и зелёная сверка ссылок (6.4, 6.5); - регрессия (7.x); - `git diff --stat HEAD -- src Dockerfile docker-compose.yml infra pyproject.toml uv.lock` — только `src/__main__.py`, `src/main.py`, `src/infra/early_stop.py`. - [ ] 8.3 `KNOWN_ISSUES.md`: пять записей удалить, шапку оставить, плюс строка «Открытых записей нет: записи лабы 3 исправлены change `fix-known-issues`.» Проверка: `grep -c '^## ' KNOWN_ISSUES.md` → 0. - [ ] 8.4 Правила — факты, которые меняет change: - `docker.md`, пункт `CMD`: сервер — PID 1, ранний обработчик до импорта приложения, почему без `init` у `api`; - `run-modes.md`: «Точка входа» (`src/__main__.py` → `early_stop` → `src.main:main()`) и пункт SIGTERM — окна A–D и окно 0; - `logging.md`: исключение для записи ранней остановки — JSON без structlog, поля и почему; строка в таблице «Где логировать»; - `infra.md`: пункт про `early_stop.py` — только stdlib, не клиент, импортируется до приложения, `disarm()` зовёт lifespan; - `balancer.md`, «Сбой на середине»: путь со слотом и без слота; - `student-tests.md`: - исключения ссылаются на существующие файлы, команды драйвера для пересъёмки; - стенд отказов: `init: true` у PostgreSQL и проверка журнала; - `bench.md`: события фазы `failover` — поток по контейнеру цели; `host_state.swapouts_delta` пишется и при 0. Проверка: `grep -n "KNOWN_ISSUES" .claude/rules/*.md` — нет ссылок на удалённые записи; каждое изменённое утверждение сверено с кодом. - [ ] 8.5 `.claude/skills/run-mtusi-messenger/SKILL.md`: строки таблицы команд и примеры для `stop-at-start`, `cache-check`, `auth-storage`. Проверка: `python3 .claude/skills/run-mtusi-messenger/driver.py --help` перечисляет их, описания совпадают. - [ ] 8.6 `AGENTS.md`: - вступление: change `fix-known-issues` в перечне и что он исправил; число changes в архиве — по факту; - таблица команд: `make failure_checks` — проверка журнала PostgreSQL; - карта кода: `src/__main__.py`, новый `src/infra/early_stop.py`, `spec_coverage.py`, `run_failures.py`, `failures.compose.yml`, `bench/run.py` (поток событий у `failover` тоже); - карта evidence: `evidence/cache/` и `evidence/auth/` — новые описания, `evidence/failover/` — `stop-at-start.md`, `evidence/tests/` — файл проверок change; - «Переход в следующую лабу»: доказательства исключений снимаются заново (`make test_isolated` + `cache-check`, `auth-storage`, `make test-persistence`, повтор после рестарта API), иначе сверка красная. Проверка: `grep -n "early_stop\|fix-known-issues\|cache-check" AGENTS.md` находит новые строки. - [ ] 8.7 `REPORT.md`, свежий Read: - шапка: `fix-known-issues` в списке «Сделано по changes». Абзац о проверке из чистого clone — в 9.3; - таблица доказательств — новые строки с командой, наблюдением и файлом: - остановка реплики во время старта (`stop-at-start.md`); - исключения сверки на стенде лабы 3 (`hits.md`, `passwords-and-tokens.md`); - регрессия `fix-known-issues` (файл проверок). В «Сверке с рубрикой» строку уровня 4 про SIGTERM дополнить; - «Эксперименты и отказы»: в таблице ручных отказов строка «`docker stop` стартующей реплики» с «до/после». Фразы о `swapouts_delta` со ссылкой на `KNOWN_ISSUES.md` (абзац о проверке хоста, раздел «Цена масштабирования») — «поле не записано, дефект паспорта исправлен change `fix-known-issues`, метки не правились»; - «Ограничения и следующие шаги»: - «Известные дефекты» — открытых нет, что исправлено; - окно 0 — ограничение; - «Следующие шаги» без исправленных пунктов; - пункт «SIGTERM во время старта реплики теряется» в «Поочерёдная замена и миграции» — по решению 7; - «Использование ИИ»: восьмой change, решение автора исправить записи отдельным change (2026-10-13). Проверка: `grep -n "не исправлены\|evidence лабы 2" REPORT.md` — пусто; `grep -n "теряется" REPORT.md` — только про окно 0 (запуск интерпретатора). - [ ] 8.8 Файлы change: отметки задач из журнала в `tasks.md`; раздел «Найдено в apply» в `design.md`, если было что найти. - [ ] 8.9 Финал документов: - `make lint`, `make check`, `openspec validate fix-known-issues --strict` — код 0; - grep секретов из 6.3 по новым и изменённым файлам `evidence/` — пусто; - commit 12. Проверка: дерево чистое. ## 9. Итоговая проверка из чистого clone - [ ] 9.1 По разделу `REPORT.md` «Запуск из чистого clone» и образцу `evidence/tests/clean-clone-final.md`, на commit 12: - рабочий стенд — `docker compose down -v`; - `git clone --branch solution/bvt2301-safronov <репозиторий> /fix-known-issues/clean-clone`; `.env`, `config.toml`, `.venv` в клоне нет; - в клоне: `make env_setup`, `make run_docker`, `docker build --no-cache --pull` под отдельным тегом (потом удалить), `make check`, `uv sync`, `make validate PYTHON=.venv/bin/python`, `make test`, `make instances` (`python3` и `/usr/bin/python3`), `make test-persistence` со `StartedAt`, `make test-failover` для каждой реплики и `kill`, `make student_test`, `make failure_checks` (со сводкой журнала PostgreSQL), `make test_isolated`; - уборка: `docker compose down -v` в клоне, хвостов `failures` и `test-api` нет; в рабочем репозитории `make run_docker`, `make lb_stats`, `make instances`. Все команды — код 0 без правки файлов клона. Сбой — разбор: дефект кода или инструкции правится commit и проверка повторяется. - [ ] 9.2 `evidence/tests/clean-clone-final.md` — переписать на commit 12: дата, результаты, «Прошлая такая проверка (commit `dbb9150`) — в истории этого файла». Пароли не выводить. - [ ] 9.3 `REPORT.md`, свежий Read: - шапка: проверенный из чистого clone commit и дата, что менялось после него — только документы; - строка таблицы доказательств «Итоговая проверка из чистого clone». - [ ] 9.4 Финал: - отметки 9.x в `tasks.md`; - `openspec validate fix-known-issues --strict`; - commit 13, дерево чистое; - `graphify update .`. Итог apply для основной сессии: - хэши коммитов; - числа «до/после»: `stop-at-start`, красный и зелёный `failure_checks`, сверка событий; - проверки хоста; - расхождения, если были.