Whilly v4.0.0 (2026-04-29) перевёл оркестратор на hexagonal-архитектуру (whilly/core, whilly/adapters, whilly/cli, whilly/worker) с Postgres-бэкендом и HTTP remote workers. При этом legacy v3-код был оставлен на один релизный цикл для обратной совместимости:
“Legacy v3 CLI lives in whilly/cli_legacy.py for one release cycle and will be removed in a v4.1+ follow-up.” — CHANGELOG.md, v4.0.0
Текущее состояние (боли):
Проблема
Влияние
cli_legacy.py (~900 строк, 37 KB) — полный v3 оркестратор, не используется в v4
Флаги по умолчанию False с v3.3.0, маршрутизируются через legacy CLI
README.md строки 71–364 — v3 документация с предупреждением “do not work on v4”
Путает новых пользователей, дублирует информацию
whilly/dashboard.py:1259 — help text содержит WHILLY_WORKTREE=1
Ссылка на удалённый config-параметр
whilly/config.py строки 89–90 — WORKTREE и USE_WORKSPACE поля
Dead config, не используется v4 dispatcher’ом
Тесты test_project_board.py, test_log_viewer.py — импортируют legacy-символы через wildcard from whilly.cli import
Сломаются после удаления cli_legacy
Цель: Оставить только v4 codebase. После cleanup: все тесты проходят, ruff чист, mypy --strict whilly/core/ проходит, import-linter контракт сохранён.
2. Целевая аудитория
Роль
Что использует
Частота
Разработчик (contributor)
Кодовая база, IDE, ruff, mypy
Ежедневно
QA-инженер
pytest, CI pipeline, CHANGELOG
При каждом MR
DevOps
pyproject.toml, entry points, CI
При релизе
Новый пользователь
README.md, whilly --help
При onboarding
3. User Stories
#
User Story
Фаза
US-1
Как разработчик, я хочу открыть whilly/ и видеть только v4 модули, чтобы не путаться между legacy и актуальным кодом
Phase 1
US-2
Как QA-инженер, я хочу чтобы pytest -q проходил без legacy-зависимостей, чтобы тесты отражали реальный codebase
Phase 1
US-3
Как новый пользователь, я хочу читать README и видеть только актуальные команды (whilly run, whilly plan, whilly init), чтобы не пробовать несуществующие v3-примеры
Phase 2
US-4
Как DevOps-инженер, я хочу чтобы pyproject.toml не содержал зависимостей, нужных только legacy-коду (e.g. psutil для tmux)
Phase 2
US-5
Как contributor, я хочу видеть в CHANGELOG чёткий перечень удалённого, чтобы понимать breaking changes при обновлении
Phase 2
4. Функциональные требования
Phase 1 — Удаление legacy-модулей
ID
Требование
Acceptance Criteria
F1.1
Удалить файл whilly/cli_legacy.py
Файл отсутствует в дереве; git status показывает deleted; grep -r cli_legacy whilly/ — 0 совпадений (кроме CHANGELOG)
F1.2
Удалить файл whilly/tmux_runner.py
Файл отсутствует; grep -r tmux_runner whilly/ — 0 совпадений (кроме CHANGELOG); from whilly.tmux_runner нигде не импортируется
Переписать whilly/cli/__init__.py — убрать wildcard import из cli_legacy, убрать legacy fallback в main()
from whilly.cli_legacy нигде в пакете; main() маршрутизирует только v4 subcommands (plan, run, dashboard, init); неизвестная subcommand → help/error, а не legacy fallback
F1.5
Удалить config-поля WORKTREE и USE_WORKSPACE из WhillyConfig (whilly/config.py:89-90)
CLAUDE.md описывает только v4 архитектуру; grep -c "tmux_runner\|worktree_runner\|cli_legacy\|plan-level workspace" CLAUDE.md ≤ 2 (только в “what was removed” контексте)
F2.7
Удалить зависимость psutil из pyproject.toml если она нужна только legacy-коду
grep psutil whilly/*.py whilly/**/*.py — используется в resource_monitor.py → вероятно остаётся; иначе удалить
F2.8
Проверить whilly/prd_generator.py:178 — упоминание cli_legacy в комментарии
Комментарий обновлён или удалён
5. Не-цели
#
Что НЕ входит в scope
NG-1
Рефакторинг v4 модулей (whilly/core, whilly/adapters, whilly/worker) — только удаление legacy
NG-2
Добавление новой функциональности (новые subcommands, новые adapters)
NG-3
Миграция данных из v3 .whilly_state.json → Postgres (отдельная задача)
NG-4
Удаление whilly/orchestrator.py, whilly/task_manager.py и других shared-модулей, которые могут использоваться и v4
NG-5
Изменение .importlinter контракта — только проверка что он проходит
NG-6
Удаление модулей whilly/dashboard.py, whilly/reporter.py, whilly/state_store.py — они могут использоваться в v4 косвенно; требуют отдельного анализа
NG-7
Изменение entry points в pyproject.toml (они уже указывают на v4)
Проверить — используется в resource_monitor.py → вероятно остаётся (F2.7)
platformdirs
≥4.0
Остаётся (user config paths, secrets.py)
keyring
≥24.0
Остаётся (secret store, secrets.py)
pytest
dev
Остаётся
ruff
dev, ==0.11.5
Остаётся
mypy
dev, ≥1.8
Остаётся
import-linter
dev, ≥2.0
Остаётся
11. Risks & Mitigations
Риск
Вероятность
Влияние
Mitigation
Тесты v3, замаскированные wildcard import в cli/__init__.py, сломаются после удаления cli_legacy
Высокая
Среднее
grep -rn "from whilly.cli import" tests/ перед удалением — найти все прямые зависимости (_finalise_project_board, _log_event, _emit_json); починить поштучно
Внешние скрипты/CI используют whilly --tasks или whilly --resume (v3 CLI)
Средняя
Высокое
Проверить .github/workflows/, Makefile, scripts/ на v3 CLI вызовы; добавить deprecation error message с подсказкой v4 эквивалента
psutil используется не только в legacy (resource_monitor.py)
Средняя
Низкое
grep -rn "psutil" whilly/ перед удалением; если используется → оставить
Shared-модули (orchestrator.py, task_manager.py, reporter.py) ломаются без cli_legacy импортов
Низкая
Высокое
Эти модули не импортируют cli_legacy напрямую; проверить grep -rn "import.*cli_legacy" whilly/
CLAUDE.md описывает v3 архитектуру, Claude Code будет генерировать несоответствующий код
Средняя
Среднее
Обновить CLAUDE.md в Phase 2 (F2.6); убрать run_plan, build_task_prompt, workspace/worktree описания
Пользователи, обновившиеся с v3, не поймут почему --workspace / --worktree не работают
Средняя
Низкое
Добавить в whilly --help секцию “Removed in v4.1” или informative error при попытке использовать старые флаги
whilly/dashboard.py help text ссылается на удалённый WHILLY_WORKTREE
Высокая
Низкое
Удалить строку в Phase 1 (F1.6), включить в тот же коммит что и config cleanup
Blast radius mapping — граф зависимостей показал 5 точек поломки (3 файла удаления + wildcard re-export + 4 тест-файла), а не очевидные 3 файла.
Порядок имеет значение — удалять нужно “снизу вверх”: тесты → cli/__init__.py → сами файлы. Иначе test suite падает целиком и отлаживать сложнее.
psutil — ложный друг — кажется legacy, но resource_monitor.py его использует в v4. PRD фиксирует это как проверочный шаг (F2.7), а не безусловное удаление. ─────────────────────────────────────────────────