Files
mtusi2026lab3/openspec/changes/fix-known-issues/tasks.md
T
2026-10-13 16:13:04 +03:00

588 lines
37 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <noreply@anthropic.com>`. Push,
checkout, reset, stash, rebase нельзя; `git revert` в задаче 3.6 —
можно.
- **Стенды.** Удалять и пересоздавать можно `mtusi-lab3` (рабочий),
`mtusi-bench` и `mtusi-lab3-failures`. Чужие проекты (`mtusi-lab2` и
другие) не трогать.
- **Упавший тест или прогон** — сначала разбор и названная причина,
потом правка (AGENTS.md). Правка кода — новый commit и повтор
проверки.
- **Журнал этапа** — `<scratchpad>/fix-known-issues/journal.md`
(scratchpad сессии apply): хэши, ключевые строки выводов, заметки для
«Найдено в apply». Отметки задач до 8.8 тоже ведутся там: паспорт
меток `bench/` пишет `git.dirty`, и перед каждым `make bench_*`
`git status --porcelain` должен быть пуст. В файлы change отметки
переносятся в 8.8.
- **`REPORT.md` может править основная сессия.** Перед каждой правкой —
свежий Read. Чужие изменения не откатывать и от своего имени не
коммитить: спросить основную сессию.
- **Долгие команды** — всё дольше пары минут — фоном, журнал в
`<scratchpad>/fix-known-issues/<имя>.log`:
```sh
nohup make <цель> > <scratchpad>/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 > <scratchpad>/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=<scratchpad>/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 <commit 3>`, затем `git
commit`, сообщение commit 4 с телом «This reverts commit <хэш>.» и
строкой `Co-Authored-By`. Проверка: `git diff <commit 2> 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 > <scratchpad>/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 > <scratchpad>/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 > <scratchpad>/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 >
<scratchpad>/fix-known-issues/load-rollout.log 2>&1 &`, затем `make
rolling_update > <scratchpad>/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 > <scratchpad>/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 > <scratchpad>/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 > <scratchpad>/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 > <scratchpad>/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=$?"' > <scratchpad>/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 <BASE> 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 <репозиторий>
<scratchpad>/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`, сверка событий;
- проверки хоста;
- расхождения, если были.