Мастер спецификации

Что такое мастер

Мастер превращает линейную цепочку discovery → /dr-prd в управляемое интервью по одному вопросу за раз, которое оператор может ветвить, ставить на паузу и перескопировать. Он существует, чтобы устранить ситуацию «агент неверно понял замысел задачи», — PRD пишется совместно с оператором.

Это тонкий оркестратор: он композирует существующие скилы discovery (движок «один вопрос за раз») и consilium (панель по требованию), никогда не переписывая их промптинг, и сохраняет каждый шаг через детерминированный движок состояния.

Четыре возможности

1. Вложенное углубление с автозахватом контекста. Оператор может уйти в сложный подвопрос в боковой ветке и вернуть вывод в основную ветку, не таская вручную идентификатор сессии. Состояние привязано к ID задачи; захваченный контекст — это сохранённый кадр углубления, содержащий ссылки на прежние ответы, а не копию; он разрешается при возврате, и вывод записывается как ответ на родительский вопрос.
2. Consilium по требованию. Для сложного решения созывается панель через скилл consilium, а вердикт фиксируется как узел-решение графа и ребро «resolves».
3. Перескопирование по ходу. Добавление или пересмотр требования, смена цели выставляют флаг «требуется переисследование» или «требуется перепланирование». В v1 само переисследование и перепланирование остаются за подтверждением оператора — отслеживание флагов без автозапуска.
4. Эмиссия графа знаний и зависимостей. Концепты, требования и решения, всплывшие в интервью, эмитируются узлами и рёбрами графа в отдельный артефакт для приёмника графа.

Модель состояния

Состояние — это append-only журнал событий JSONL; текущее состояние есть проекция (свёртка) над событиями. Именно это делает интервью возобновляемым и ветвимым:

• Возобновление — воспроизведение журнала; повторный запуск /dr-wizard продолжает, а не начинает заново.
• Ветвление — производный стек углублений (push / pop) плюс родительские ссылки.
• Идемпотентность — при проекции побеждает последнее событие для каждого идентификатора вопроса.
• Каждое событие несёт версию схемы и монотонный порядковый номер.
• Терминальное событие «finalized» закрывает интервью; открытые кадры углубления снимаются как заброшенные. /dr-prd потребляет только финализированный артефакт — незавершённое интервью никогда не авторитетно.

Файлы лежат в gitignore-дереве рантайма: datarim/wizard/{TASK-ID}.wizard.jsonl содержит журнал событий интервью (виды: meta, вопрос, ответ, вход в углубление, выход из углубления, флаг, финализация).

API движка

Потребители подключают библиотеку состояния и вызывают её публичные функции — инициализация, добавление вопроса, ответ, чтение ответа, вход и выход из углубления, перескопирование, флаги, финализация, статус, валидация, узел графа, ребро графа. Движок — единственная точка корректности: запускайте валидацию до того, как любой потребитель доверится журналу. Она проверяет сбалансированность push и pop, монотонность номеров, известность видов событий и версии схемы, а также что каждое ребро графа ссылается на существующий узел. Валидация отклоняет — она никогда не чинит по мере возможности.

Граф-артефакт

datarim/wizard/{TASK-ID}.graph.jsonl — документированный контракт приёма для приёмника графа: по одному JSON-объекту на строку — заголовок meta, затем узлы (тип: концепт, требование или решение) и рёбра (отношение: зависимость, уточнение или разрешение).

Граф уходит НАРУЖУ, поэтому метки узлов редактируются на границе приёмника (формы токенов, bearer-учётные данные, блоки приватных ключей, формы «пользователь-пароль-хост», домашние пути, адреса частных диапазонов) до записи. Локальный журнал интервью хранит сырой текст. Обогащение, слияние и семантика запросов принадлежат приёмнику графа — этот скилл лишь эмитирует по контракту и не строит приёмник.

Композиция с /dr-prd

/dr-prd получает единственный неинвазивный хук: если для задачи существует финализированный артефакт мастера, команда потребляет его сводку требований и граф вместо запуска обычного интервью discovery. Хук идемпотентен — повторный запуск перечитывает тот же артефакт и никогда не потребляет дважды. Если артефакта мастера нет, обычный путь discovery не меняется. Так сохраняется один движок интервью с двумя эргономиками входа, без второго расходящегося прохода discovery.

Безопасность

Обеспечивается движком, а не прозой: гейт инъекций экранирует обратный слеш, кавычку и табуляцию и отклоняет перевод строки, возврат каретки, прочие управляющие символы C0 и DEL; списки разрешённого для идентификаторов вопросов и узлов, слагов категорий и закрытых перечислений типов и отношений; удержание путей строгим шаблоном ID задачи, отказ от целей-симлинков и дозапись под блокировкой; редактирование данных на исходящем приёмнике графа.

Когда остановиться

Тот же контракт, что у discovery: все ветки разрешены (нет открытого кадра углубления), критерии готовности определены, не осталось вопроса, ответ на который изменил бы подход. Затем финализация, валидация и выпуск сводки требований. Не переинтервьюируйте — односложные подтверждения означают, что объём ясен; закругляйтесь.