goon-game/docs/BEADS_WORKFLOW.md

Beads: отслеживание выполнения плана

Beads инициализирован в ~/tmp/goon-game поверх embedded Dolt. Git remote настроен:

origin = ssh://git@git.pryanik.synology.me:2222/huncode/goon-game.git
master tracks origin/master

Обычный Git push публикует исходники и экспорт .beads/issues.jsonl. Embedded Dolt остаётся source of truth. Локальная запись Dolt remote создана, но отдельная Dolt-история не публикуется без явного разрешения владельца.

Источники требований:

• DEVELOPMENT_PLAN.md — утверждённый GDD + TDD + production roadmap;
• CURRENT_ROADMAP.md — ближайшая последовательность работ для существующего vertical slice.
• STAGE_REGISTRY.md — обязательная stage-классификация всех Beads от Prototype до Release Candidate.

Структура backlog

• master epic: goon-game-plan;
• 16 доменных эпиков goon-game-e01 … goon-game-e16 из раздела 62 основного плана;
• milestones Prototype, Vertical Slice, Production, Alpha, Beta и Release Candidate;
• предметные задачи с acceptance criteria, приоритетами и зависимостями;
• уже подтверждённые кодом и QA элементы закрыты с причиной.

На 18 августа 2026 года в snapshot находятся 78 beads. Эти числа нельзя трактовать как точный процент готовности, потому что в базе смешаны эпики, features и задачи разного размера.

Этапы 0–5 не содержат незакрытых primary-задач. Текущий primary gate — Stage 6: production content 55–70 уровней, четыре мира, расширение mechanics/challenges и production progression. Ограничения внешнего Stage 5 evidence зафиксированы в STAGE5_HUMAN_PLAYTEST_RESULT.md.

Ежедневные команды

Выполнять из ~/tmp/goon-game:

bd status
bd ready --exclude-type epic
bd list --all --tree

Посмотреть задачу и её зависимости:

bd show goon-game-bot-framework
bd dep tree goon-game-milestone-vslice

Начать работу:

bd update goon-game-bot-framework --claim

Закрыть после выполнения acceptance criteria:

bd close goon-game-bot-framework --reason "Acceptance criteria выполнены; проверки зелёные"

После изменения графа:

bd dep cycles
bd export --output .beads/issues.jsonl
./scripts/check-stage-assignments.sh

Завершение сессии:

git add .
git commit -m "<описание изменения>"
git pull --rebase
git push
git status --short --branch

Правила ведения

1. Не закрывать задачу по факту написания кода — сначала выполнить её acceptance criteria и проверки.
2. Новую найденную работу добавлять дочерней к одному из 16 эпиков и связывать blocking dependency, если она влияет на milestone.
3. Реальные softlocks и непроходимые уровни заводить как bug с P0/P1, а не прятать внутри общего balance task.
4. Vertical Slice закрывать только после 10/10 passed, внешнего playtest и остальных зависимостей в его дереве.
5. Не редактировать .beads/issues.jsonl вручную: source of truth — embedded Dolt в .beads/embeddeddolt.
6. Git remote обязателен для исходников и JSONL snapshot; после каждого изменения backlog экспортировать JSONL, коммитить и делать push.
7. bd dolt push публикует отдельную внутреннюю историю и выполняется только после явного разрешения владельца.
8. Каждая Bead обязана иметь минимум один stage-N, ровно один primary-stage-N и совпадающую metadata primary_stage; новые задачи без этой классификации не должны попадать в commit.