Progress Control — руководство владельца
- 01Этот документ — для человека. Контракт системы — PROP-043 (грамматика) и PROP-047 (инструмент и кампании); план кампании — SPEC-ACTUALIZATION-CAMPAIGN-v0.1.
- Здесь — как этим пользоваться, что смотреть и какие решения ждут лично вас.
- Язык — русский, потому что аудитория этого файла — владелец проекта.
1. Как читать маркеры в спеках
02Маркер — XML-тег в тексте. Читается как «стадия/состояние [+ что делать]»:
03<status stage="impl" state="work"/>
04— «реализация в процессе». То же самое сокращённо: @impl (state=work
подразумевается). @test/plan — «тестирование запланировано».
05Полный словарик:
| stage | значит |
|---|---|
idea |
идея, ещё не специфицирована |
spec |
пишем/написали спеку |
impl |
реализуем/реализовано |
test |
тестируем/протестировано |
doc |
документируем/задокументировано |
freeze |
замораживаем (plan → work → done = заморожено; разморозка = смена маркера назад) |
unknown |
«смотрел и не понял» — явный запрос на триаж |
| state | значит |
|---|---|
plan |
собираемся |
work |
делаем |
done |
сделали (для этой стадии) |
hold |
сознательно отложено |
08Необязательные поля:
- 09
action— вердикт «что делать» (continue— доделать;drift— разъехалось с реальностью, свести;rework— переделать;remove— убрать); actionstage— на какую стадию действует action (remove+actionstage="doc"= «удалить документацию»);audience— для кого это документировать (user— пользователь vibevm,author— автор пакетов,dev— мы сами);comment,ref(ссылка на задачу DRIFT-NNN или spec://-анкер).
10Куда можно ставить маркер — шесть гранулярностей (PROP-043 §3.8):
- 11в преамбуле, до первого заголовка (весь документ). В файле без преамбулы — а это стандартная форма в этом репозитории — маркер сразу после первого заголовка и есть документный;
- отдельной строкой сразу после заголовка (секция) — кроме первого заголовка файла без преамбулы: там эта позиция занята документным маркером;
- первым или последним токеном внутри абзаца (абзац);
- последним токеном внутри элемента списка (элемент списка);
- внутри ячейки таблицы (ячейка);
- парным тегом вокруг текста (фрагмент).
- Любая из этих единиц может нести якорь факта
@fact:<ID>в начале — тогда она адресуема поspec://…#<ID>. Прежнее написание##<ID>значит ровно то же и по-прежнему читается, но пишется теперь первое. Закон anchored-when-marked: размеченный факт обязан быть заякорен; - Одинокий маркер между абзацами — ошибка, инструмент его отвергнет.
2. Ежедневные команды
12Команды ниже — утверждение о том, что умеет инструмент сегодня, а не пример: забор входит в тело этого факта, поэтому любая правка внутри него приводит факт к пересуду. Первая строка когда-то утверждала обратное тому, что есть на самом деле, и прожила так долго именно потому, что забор нельзя было осудить.
13vibe progress check --exhaustive # валидация разметки; С 2026-08-06 стоит и в гейт-панели
vibe progress report --md # статус дерева таблицей
vibe progress report --md --view todo # что доделать
vibe progress report --md --view qa # что тестировать
vibe progress report --md --view remove # что удалить
vibe progress report --md --view doc --audience user # оглавление user-доки
vibe progress weave --digest # карта всего корпуса, влезает в контекст LLM
- 14Правило гигиены между кампаниями (одно): правите юнит спеки — обновите его маркер в том же коммите.
- Всё остальное караулит инструмент.
3. Кампания: запуск, наблюдение, ваша роль
- 15Кампания живёт в
campaigns/<id>/(напримерcampaigns/progress-2026-08/). - Все стадии, гейты и правила — в плане кампании; здесь — ваша сторона.
3.1 Дашборд
16node tools/progress-dashboard/serve.mjs # затем открыть http://localhost:<port>
- 17Первый экран — Resume: что не завершено (красным), что дальше, свежесть состояния (жёлтая плашка = state давно не обновлялся — загляните, жива ли сессия).
- Дальше: Корпус (дерево файлов цветом по статусу),
- Сшивка (график открытых обязательств по волнам — линия обязана падать),
- Задачи (чем занят Opus, что застряло в review).
- Дашборд read-only: он ничего не считает и ничего не может испортить.
- (Терминология: эта страница — «дашборд», не «витрина»/«storefront» — те слова заняты витриной магазина vibevm.)
3.2 Какие решения ждут лично вас (по стадиям кампании)
- 18A (scaffold): ратифицировать PROP-043; подтвердить имя зоны
campaigns/; ничего больше. - B (разметка): выборочно читать диффы батчей — маркеры и сплиты, смысл текста меняться не должен. Сигнал тревоги: любой содержательный дифф.
- C (верификация): ничего решать не нужно; полезно поглядывать на сводку X% confirmed / Y% drift — это первый измеренный уровень актуальности ваших спеков.
- D (сшивка): к вам приходят только эскалации — пары документов, чей конфликт не сходится две волны. Это концептуальные развилки: нужен ваш вердикт, какая трактовка верна. Плюс все правки спек по мотивам sync-from-code показываются вам ДО применения — как и всегда в этом проекте.
- E (кодирование): приёмка спорных PR после ревью Fable; вердикты по
remove/reworkспискам (удалять ли, отключать ли фичефлагом). - F (планы): три плана (release / улучшения / идеи) приходят к вам на утверждение приоритетов.
- G (документация): вычитка глав двух гайдов — регистр и правда. Все примеры в доке уже реально исполнялись (это гарантия конвейера), ваша проверка — «то ли это, что я хотел сказать людям».
3.3 Если сессия оборвалась (бюджет, питание, что угодно)
19Ничего не чините руками. Новая сессия (любая — Fable или Opus) начинает с:
20прочитай campaigns/<id>/run/RESUME.md и продолжай по нему
- 21RESUME.md сгенерирован журналом и говорит буквально: какой шаг не закрыт,
какие файлы откатить (
git restore …), что делать следующим. - Максимальная потеря при любом обрыве — один шаг (один файл разметки / один юнит верификации / одна задача).
3.4 Перезапуск через месяц (и далее регулярно)
22vibe progress rescan --baseline campaigns/<прошлая>/baseline.json
- 23Инструмент сам разложит корпус на «новое / изменившееся (перепроверить) / нетронутое (переносим вердикт)». Дальше — тот же цикл, но объёмом O(дельты): дни, не месяц.
- Между кампаниями из зоны кампании хранятся только четыре вещи
(PROP-047 §5.4):
baseline.json(ускоритель перепроверки),deferrals.md(открытые хвосты),harvest/(сырьё для доки) иtasks/(корпус задач). Маркеры тоже переживают кампанию, но они живут в спеках — это корпус, а не зона. - Всё остальное можно стирать в любой момент — знание не теряется.
4. Аварийные случаи
- 24Маркер спорный / кажется неправдой — правьте смело или ставьте
unknown: маркер — это state-слой (как WAL), а не нормативный текст; ваша правка законна всегда. - Инструмент ругается на легальный, по-вашему, случай — это баг
инструмента или пробел PROP-047; фиксируйте как обычный баг, маркер
временно допустимо сопроводить
comment="check false-positive: …". - Дашборд показывает странное — он лишь проекция; истина в
campaigns/<id>/run/state/*.json, а выше неё — маркеры в спеках. Конфликт решается перегенерацией (vibe progress scan), никогда правкой JSON. - Хочется бросить кампанию посреди — безопасно в любой момент: границы батчей закоммичены, RESUME.md всегда говорит, где вы. Возврат через месяц = п. 3.4.