[Epic] docs: аудит Markdown-документации после v1.8.0 — устранение дрейфа

[ArtVsMark]

✅ Разблокирован (2026-07-14): эпик #362 закрыт (PR #387) — предусловие снято, работы этого эпика можно начинать.

Цель

Устранить накопившийся дрейф Markdown-документации: привести все *.md в
соответствие с кодом на main, дозаполнить незавершённый переход на v1.8.0,
починить фактические ошибки, актуализировать архитектурные каноны и поставить
CI-барьер против повторения.

Источник

Разовый аудит всех 34 tracked-файлов *.md (~8 900 строк), срез
origin/main после PR #380 (тег v1.8.0 от 2026-07-14 + 10 смерженных PR).
Метод: перекрёстная сверка с кодом по file:line, сверка статусов issue/PR с
GitHub API, механическая проверка ссылок/якорей/сирот, подсчёт тестов в
изолированном Python 3.12-окружении.

Сводка находок

Вес	Кол-во
🔴 Критично	3
🟠 Средне	24
⚪ Мелко	18
🟣 Сопутствующее в коде	6

Вердикт: документация в целом жива (все ссылки/якоря валидны, CHANGELOG
дисциплинирован, docs/api.md в полном паритете с кодом), но есть: (1) одна
незакрытая релизная дыра v1.8.0, (2) пласт свежего дрейфа от волны эпика #342,
(3) сильно отставший docs/architecture.md, (4) точечные фактические ошибки,
(5) два «мёртвых» документа.

Ключевые находки по группам

1. Незакрытый релиз v1.8.0

Релизный PR #361 обновил только CHANGELOG/CHECKPOINT/CLAUDE/history и не тронул:

• 🔴 docs/versions.md:28–38 — таблица «Эволюция версий» кончается колонкой
  v1.7.0, колонки v1.8.0 нет; при этом history.md:393 объявляет
  versions.md «каноническим живым источником» метрик — канон отстал от архива,
  CI это не проверяет.
• 🟠 CHECKPOINT.md:79 — «CHANGELOG § [1.7.0]» при snapshot v1.8.0;
  :88–96 числит закрытый [Epic][PR-7] SQLite persistence: история запусков и учебные данные #130 «открытым фронтом».

2. Дрейф после эпика #342 (история/правила/lint/insights)

• 🟠 Меню теперь 0–5 («5. Подучить», cli/interactive.py:245), но «режимы
  0-4» осталось в CLAUDE.md:84, architecture.md:16, project-structure.md:16,
  скриншот меню grader-workflow.md:37–48 без пункта 5. Бонус (код): промпт
  core/locales/ru.json:60,65 всё ещё «[0-4]».
• 🟠 web-current.md противоречит сам себе: «четыре раздела» (:41, :325,
  ASCII-схема :318) vs «шесть» (:113).
• 🟠 configuration.md:76 «Полный список параметров» без трёх ключей
  insights_* (config.py:66–68), за которыми rules-insights.md:106 шлёт
  именно сюда.
• 🟠 README отстал на ~3 релиза: секция «Безопасность» (:103–110) без
  opt-in --sandbox; фич-лист (:26–44) без --stats/--history/--insights/
  --lint/глоссария.

3. Отставший docs/architecture.md

• 🔴 В таблице модулей и DAG отсутствуют 5 модулей: core/diag_log.py
  (feat(logging): эпик #146 — opt-in диагностическое логирование сети/OAuth с редакцией секретов #341), core/tracer.py (feat(core): трассировщик пошагового исполнения — sys.settrace → JSON-трейс #318), web/playground.py (feat(web): песочница MVP — редактор + stdin + вывод, запуск без тест-кейсов #317),
  web/rules_adapter.py, web/insights_adapter.py (feat(web): API разделов «Правила»/«Подучить» — /api/rules, /api/insights (часть #348) #379). Плюс ~15
  недостающих рёбер DAG и 2 фактические ошибки (несуществующий web/locales/
  на :32/:111; ложный leaf-клейм rules/ на :51; фантомное ребро
  grader_core → sandbox на :112).

4. Фактические ошибки (док ≠ код)

• 🔴 logging.md:34 — «--verbose включает диагностику» — не включает
  (только --diagnostic, cli/__init__.py:415); собьёт пользователя.
• 🟠 server-mode.md:148 — «статуса отмены нет», хотя cancelled есть (feat(web): отдельный статус "cancelled" в /api/v1/runs — решить до заморозки контракта #296).
• 🟠 grader-workflow.md:265 + код options.py:103 — неверное имя пакета
  stepik-grader[watch] (правильно stepik-python-grader).
• 🟠 «Док опережает код»: поле lint в result-contract.md:120 ни один
  продюсер не создаёт; заявленная запись lint в историю не реализована
  (LintRecord нигде не конструируется) — категория «lint» в «Подучить»
  недостижима.

5. Статусы, противоречия, мёртвые доки

• 🟠 docs/README.md:30 подаёт закрытые issue как «будущие задачи»;
  CLAUDE.md противоречит сам себе про feat(version): различать dev и release в выводе --version #163 (:181 vs :273).
• 🟠 Шаблоны .github/ несут отменённую политику «CHANGELOG при завершении
  фичи» вместо «в каждом PR» (docs(changelog): политика краткости записей + ротация старых версий в архив #373).
• ⚪ docs/claude-handoff.md мёртв как task-list (все постановки закрыты);
  docs/audit-2026-07.md — все P0/§9 реализованы, но внутри не помечено.

Что в порядке (не трогаем)

Ссылки/якоря (все 453 валидны), ротация CHANGELOG, docs/api.md (полный
паритет с кодом), result-contract.md (кроме lint), SECURITY.md,
trace-format.md, форматы тест-кейсов, leaf-инварианты CLAUDE.md, счётчики
глоссария (581/832/28).

Почему CI это пропускает

Guard-скрипты покрывают форму, не содержание: check_version_consistency.py
(pyproject/CHECKPOINT-маркер/CHANGELOG-заголовок/CLAUDE-строка) и
check_docs_guardrails.py (README ≤220, ссылки+якоря, «каждый docs/*.md в
README», ≤3 версий в CHANGELOG). Слепые зоны: versions.md не проверяется
вообще; проза CHECKPOINT, статусы issue, метрики и счётчики — невидимы.

Дочерние issue (порядок = рекомендуемый порядок реализации)

• fix(docs): дозакрыть переход на v1.8.0 — versions.md, CHECKPOINT, CONTRIBUTING, installation #382 — fix(docs): дозакрыть релиз v1.8.0 (versions.md + CHECKPOINT + CONTRIBUTING + installation)
• docs: синхронизировать доки с волной эпика #342 (меню 0-5, web-разделы, ключи insights_*, README) #383 — docs: синхронизация с эпиком [Epic] Учебные инсайты: разделы «Правила/PEP» и «Подучить» на SQLite-истории #342 (меню 0-5, web-разделы, ключи insights_*, витрины, README, --history/--diagnostic)
• fix(docs): фактические ошибки в доках (logging --verbose, server-mode cancelled, имя пакета, api.md) + wiring lint #384 — fix(docs): фактические ошибки (logging --verbose, server-mode cancelled, имя пакета, api.md, trace-format, ADR, шаблоны) + wiring lint
• docs(architecture): актуализировать architecture.md и project-structure.md под текущий код #385 — docs(architecture): актуализация architecture.md + project-structure.md
• chore(docs): барьер против дрейфа — CI-guard versions.md, релизный чеклист, архивация claude-handoff #386 — chore(docs): барьер против повторения (guard versions.md, релизный чеклист, архивация claude-handoff, банер audit-2026-07)

Примечание: после PR #387 (#362) в web-current.md/app.js/index.html снова
изменилось поведение web («Настройки» с выбором языка ?lang=, режимы 3/4,
«Разбор») — учесть в #383/#385 при синхронизации доков.

Acceptance criteria (эпика)

• docs/versions.md содержит колонку последнего релиза; ни один док не
  называет прошлый релиз актуальным
• Число пунктов меню (0–5) и набор web-разделов согласованы во всех доках и
  локалях кода
• Все ключи GraderConfig документированы в configuration.md
• docs/architecture.md и project-structure.md содержат все модули и рёбра
  DAG, подтверждённые импортами; ложных клеймов нет
• Фактические ошибки из § 4 исправлены (либо код приведён к доку по lint)
• CI ловит отсутствие колонки последнего релиза в versions.md
• claude-handoff.md заархивирован/помечен; входящие ссылки поправлены