gennady 0.8.3 → 0.8.4-draft.2

package/ai/flow-sim/PROTOCOL.md

@@ -0,0 +1,159 @@
+# SDD v2 Flow Simulation Protocol
+
+## Цель
+
+Инструменты (`cli/cmd/*`, `shared/sdd/*`) покрыты юнит-тестами — это проверяет их изолированно.
+Директивы (`ai/directives/sdd-v2/*.directive.xml`) — не код, юнит-тест их не запустит. Единственный
+способ проверить, что LOGIC_SWITCH выбирает правильную ветку, что STOP срабатывает там, где написано,
+и что агент не тащит в контекст директиву, которую не должен был загружать — живой прогон агентом
+по фиксированному сценарию, с последующей проверкой трейса против текста директивы.
+
+Это верификация ветвлений и лайфсайклов флоу, а не самих артефактов SDD (спек / тикетов) — те
+проверяет `sdd-check` / `gennady lint`.
+
+## Роли
+
+**Executor** — дешёвая модель, слепой прогон. Получает ТОЛЬКО:
+
+- карту сценария из `ai/flow-sim/scenarios/` БЕЗ секции `## Checkpoints` (оркестратор вырезает её
+  перед выдачей — Executor не должен знать, что проверяют),
+- фикстуру (собирает её сам по рецепту карты, дословно),
+- путь к изолированной песочнице (выдаёт оркестратор).
+
+Executor не знает, что он участвует в проверке директивы — он просто выполняет роль оператора SDD
+и агента SDD как обычно, честно, до `## Stop`.
+
+**Verifier** — сильная модель. Получает: полную карту сценария (включая Checkpoints), TRACE от
+Executor, и `git diff` фикстуры (что реально изменилось на диске). Выносит вердикт по каждому
+Checkpoint: `CONFIRMED` (трейс + текст директивы совпадают) или `VIOLATED` (с уликой — строка трейса
+против строки директивы). Отдельно — секция «Импровизации»: свободные находки о том, что Executor
+сделал сверх карты, или недоделал из предписанного.
+
+**Arbiter** — разводит `VIOLATED` на два принципиально разных случая:
+
+- **дефект директивы** — сама директива неоднозначна / противоречива / даёт агенту возможность
+  свернуть не туда при точном следовании тексту → правится директива;
+- **слабость исполнителя** — директива однозначна, Executor её просто не выполнил → это сигнал
+  _упростить_ директиву (слишком длинная/сложная для дешёвой модели), а не чинить директиву как
+  дефектную.
+
+Arbiter не запускается автоматически в рамках одной карты — это ручной шаг оператора после того, как
+Verifier выдал `VIOLATED`.
+
+## TRACE_FORMAT
+
+Executor пишет трейс построчно, append-only, СТРОГО в типизированном виде — свободная проза вне
+этих строк запрещена (Verifier не парсит естественный язык, он ищет типизированные записи).
+
+Канонична голая типизированная строка — префикс `T<n> | ` ОПЦИОНАЛЕН (3 прогона из 5 его теряли;
+требовать его — упрощать было не о чем упрощать, раз Verifier его фактически не использует). Verifier
+ссылается на находку по номеру строки ФАЙЛА `TRACE.md` (`строка 42`), не по `T<n>`. Executor может
+проставлять `T<n>` для собственного удобства — это не ошибка, просто не проверяется и не требуется:
+
+```
+directive: <file> loaded
+step: <STEP_ID>
+branch: <WHEN label дословно>
+tool: <команда дословно> → exit=<N>
+  output: <краткий вывод команды — что она напечатала/вернула, в одну-две строки>
+show: <перечень секций/маркеров показанного оператору блока>
+ask: <канал: AskUserQuestion|QUESTION_FORMAT> — <заголовок вопроса>
+halt: <H_*> — <причина>
+stop: per-map — <условие Stop дословно>
+operator: <вопрос агента> ← <ответ из скрипта>
+write: <путь>
+note: <отклонение/неуверенность>
+```
+
+- `directive:` — каждый файл директивы в момент, когда агент его READ_AND_USE_DIRECTIVE'ит (не при
+  каждом обращении — один раз на загрузку).
+- `step:` — каждый переход `<Step id="...">` внутри активной директивы.
+- `branch:` — дословная копия `WHEN`-условия из `LogicSwitch`/`LOGIC_SWITCH`, которое сработало (не
+  пересказ, не номер — точный текст label).
+- `tool:` — дословная команда (включая флаги, включая `--write` / его отсутствие) и код возврата.
+- `  output:` — подстрока строго ПОД своей строкой `tool:`, с отступом (двумя пробелами), краткий
+  фактический вывод этой команды (что она напечатала в stdout/stderr, или структурный итог — «3
+  units, 2 tickets, 0 orphans»). Не отдельная типизированная строка трейса — привязана к
+  предшествующему `tool:` и не имеет смысла без него. Без неё Verifier не может проверить чекпоинты
+  про СОДЕРЖИМОЕ того, что инструмент вернул (не только что он был вызван и с каким `exit=`) —
+  легитимизирована, потому что несколько прогонов её изобрели самостоятельно именно по этой причине.
+- `show:` — ОБЯЗАТЕЛЬНА для каждого содержательного сообщения оператору (decision-card, картина
+  survey, отчёт формы, манифест секций, итог гейта): перечень секций/маркеров того, что именно было
+  показано. Без этой строки чекпоинты про содержимое показанного блока непроверяемы — Verifier не
+  видит текста, который агент фактически вывел, только то, что Executor заявил строкой трейса.
+- `ask:` — каждый вопрос, заданный оператору через определённый директивой канал (`AskUserQuestion`
+  или текстовый `QUESTION_FORMAT`), с указанием канала и заголовка вопроса. Дополняет `operator:` —
+  `ask:` фиксирует ЧТО и КАК было спрошено, `operator:` фиксирует связку вопрос-ответ.
+- `halt:` — ТОЛЬКО настоящий `H_*` из текста директивы (`H_NOT_V1`, `H_NO_PORTAL`,
+  `H_SCOPE_NOT_CONFIRMED` и т.п.), с причиной в одну фразу. Остановка по карте (`## Stop`) — это
+  НЕ `halt:`, это `stop:` (см. ниже); `halt:` зарезервирована исключительно за директивными
+  H-гейтами.
+- `stop:` — остановка прогона по условию `## Stop` карты сценария (не по директивной `H_*`-гейту):
+  `stop: per-map — <условие Stop дословно>`, последняя строка трейса.
+- `operator:` — вопрос, который агент задал оператору, и какой ответ был взят (следующий неиспользованный
+  из Operator Script).
+- `write:` — КАЖДЫЙ файл, который агент создал или изменил на диске, БЕЗ ИСКЛЮЧЕНИЯ по инструменту
+  записи. Правка через Edit-подобный инструмент — тоже `write:` (`tool: edit <путь>` — если Executor
+  пишет и такую строку — фиксирует ВЫЗОВ инструмента, но не заменяет обязательную `write: <путь>`
+  для самого факта записи на диск; строки дополняют друг друга, одна не покрывает другую).
+- `note:` — любое отклонение, неуверенность, или момент, где Executor не был уверен, что делать.
+
+## Правила исполнителя
+
+- Фикстуру собрать **дословно** по рецепту `## Fixture` карты, в изолированной директории — путь
+  передаёт оркестратор, никогда не текущий репозиторий.
+- CLI-команды звать `npx tsx <worktree>/cli/gennady.ts <cmd> <args>` (путь к worktree gennady — от
+  оркестратора), НЕ `npx gennady` — фикстура не проходила path-normalizer.
+- Если `npx tsx` падает (403 / нет сети до реестра пакетов) — легитимный фолбэк:
+  `<worktree>/node_modules/.bin/tsx <worktree>/cli/gennady.ts <cmd> <args>`, с ОДНОЙ строкой `note:`,
+  фиксирующей переход на фолбэк и причину. Главное инвариант — бить строго в `<worktree>` (тот, что
+  выдал оркестратор), никогда в `~/Developer/gennady` или любой другой чужой чекаут.
+- `TRACE.md`/`DIFF.txt` прогона писать ВНЕ git-репозитория фикстуры — например, в родительском
+  каталоге песочницы, а не внутри неё. Если фикстура сама является git-репозиторием, её `git status`
+  должен читаться как «что изменил флоу» и ничего больше — файлы прогона (трейс, дифф) там не место.
+- В песочнице легитимен ТОЛЬКО baseline-коммит (`git add -A && git commit -m fixture-baseline`) ДО
+  запуска флоу. НИКАКИХ дополнительных коммитов фикстуры по ходу прогона, если карта явно не велит —
+  промежуточный коммит смешивает то, что сделал флоу, с тем, что сделал Executor, и убивает
+  `git diff`/`git --follow`-проверяемость Verifier'а (карта S11 однажды слила move+restructure в один
+  коммит и уничтожила `git --follow`-проверяемость самим этим смешением). Для карт, где сама
+  директива-первоисточник по своему тексту коммитит (например, вызывает `git mv` /
+  `git commit` как часть шага) — карта ОБЯЗАНА явно перечислить в `## Fixture` или `## Stop`, какие
+  коммиты внутри прогона легальны и на каком шаге; Executor коммитит только то, что карта так назвала,
+  ничего сверх.
+- Чтение любых файлов проекта (внутри фикстуры или директив/скиллов) — тоже `tool:`-строки в трейсе
+  (`cat <path>`, чтение через Read и т.п.), не тихие фоновые действия. Реестр правил и любые файлы
+  проекта читать ТОЛЬКО внутри песочницы фикстуры, никогда из `<worktree>` — единственное исключение:
+  `ai/directives/` и `ai/skills/` самого флоу (`v2`-директивы, которые прогон и проверяет).
+- На вопросы оператора отвечать строго по `## Operator Script` — следующий неиспользованный ответ по
+  порядку. Скрипт кончился, а агент всё ещё спрашивает → `note` в трейсе, фиксирующая расхождение, и
+  прогон завершается (это находка для Verifier, не тупик для Executor; НЕ `halt:` — это не
+  директивный `H_*`-гейт).
+- `## Stop` карты — обязательная стоп-точка. Карты режут прогон РАНЬШЕ естественного конца директивы
+  именно для этого — не жечь токены на шаги, которые чекпоинты не проверяют. Остановиться на
+  условии `Stop`, даже если директива по своему тексту продолжила бы работать — записать это как
+  `stop: per-map — <условие Stop дословно>`, последней строкой трейса.
+- Один прогон — одна карта. Не пытаться пройти сразу несколько сценариев в одной сессии.
+
+## Правила верификатора
+
+- Каждый Checkpoint сверяется ДВАЖДЫ: против TRACE (это случилось?) и против текста
+  директивы-первоисточника (это именно то, что директива предписывает?). Вердикт без второй сверки
+  не принимается — Verifier обязан процитировать директиву.
+- Вердикт по каждому Checkpoint — `CONFIRMED` / `VIOLATED`, с уликой: конкретный номер строки файла
+  `TRACE.md` (`строка 42`, не `T<n>` — префикс `T<n>` опционален и Verifier на него не полагается)
+  ПРОТИВ конкретной цитаты из директивы.
+- Секция «Импровизации» (отдельно от Checkpoints) — свободные находки:
+  - что Executor сделал, чего карта/директива не велела (лишний tool-вызов, лишняя загрузка
+    директивы, самовольное продолжение после `Stop`);
+  - что из предписанного Executor пропустил (не задал обязательный вопрос, не вызвал гейт).
+- Финальный вердикт на карту: `PASS` (все Checkpoints `CONFIRMED`, нет находок) / `PASS_WITH_FINDINGS`
+  (Checkpoints `CONFIRMED`, но есть находки в «Импровизациях») / `FAIL` (хотя бы один `VIOLATED`).
+
+## Детерминизм и повторяемость
+
+- Одна карта = один воспроизводимый прогон: фиксированная фикстура + фиксированный Operator Script +
+  фиксированный Stop → один и тот же маршрут по директивам при точном исполнении.
+- Карты версионируются в git (`ai/flow-sim/scenarios/`) — правки карты идут тем же PR-процессом, что
+  правки директив.
+- Трейсы и `git diff` фикстуры — эфемерные артефакты прогона. Пишутся в scratch-директорию ВНЕ
+  репозитория (её путь даёт оркестратор), в `ai/flow-sim/` не коммитятся.

package/ai/flow-sim/README.md

@@ -0,0 +1,39 @@
+# ai/flow-sim — симуляционная проверка SDD v2 флоу
+
+Юнит-тесты покрывают `cli/cmd/*` и `shared/sdd/*` — детерминированный код. Директивы в
+`ai/directives/sdd-v2/*.directive.xml` не код: они читаются и «исполняются» агентом-интерпретатором.
+Единственный способ проверить, что `LOGIC_SWITCH` роутит куда должен, что `STOP` держит агента, и что
+он не подхватывает директивы, которые не должен — живой прогон по фиксированному сценарию.
+
+Полный протокол ролей (Executor / Verifier / Arbiter) и формат трейса — `PROTOCOL.md`. Карты
+сценариев волны 1 — `scenarios/S<N>-<slug>.md`.
+
+## Как запустить одну карту
+
+Роль оркестратора (человек или управляющий агент):
+
+1. Взять карту из `scenarios/`, вырезать секцию `## Checkpoints` — Executor не должен знать, что
+   проверяют.
+2. Выделить изолированную песочницу (временный каталог вне репозитория) и передать её путь Executor'у
+   вместе с усечённой картой.
+3. Executor собирает фикстуру по `## Fixture` дословно в этой песочнице, разыгрывает `## Entry` +
+   `## Operator Script`, пишет `TRACE` по формату из `PROTOCOL.md`, останавливается на `## Stop`.
+4. Verifier получает: полную карту (с Checkpoints), TRACE от Executor, `git diff` песочницы. Сверяет
+   каждый Checkpoint с трейсом И с текстом директивы-первоисточника, выносит вердикт
+   `CONFIRMED`/`VIOLATED` с уликой, отдельно — секцию «Импровизации».
+5. При `VIOLATED` — Arbiter (отдельный ручной шаг) решает: дефект директивы (правится директива) или
+   слабость исполнителя (сигнал упростить директиву).
+
+## Куда пишутся трейсы
+
+TRACE и `git diff` фикстуры — эфемерные, пишутся в scratch-директорию вне репозитория (путь даёт
+оркестратор). В `ai/flow-sim/` коммитятся только карты сценариев и протокол — трейсы никогда.
+
+## Связь с юнит-тестами
+
+Юнит-тесты (`shared/sdd/__tests__/*`, `cli/cmd/*/__tests__/*`) проверяют инструменты изолированно —
+`checkReadiness`, `parseScopes`, `sdd-new`, `sdd-check` и т.д. как функции/CLI с фиксированным
+вводом/выводом. Карты здесь проверяют то, что юнит-тест не видит: правильную ли директиву агент
+выбрал и загрузил, остановился ли там, где предписан `STOP`, и вызвал ли он ожидаемый инструмент
+именно с ожидаемыми флагами (а не написал файл руками). Одно без другого не покрывает флоу целиком —
+инструмент может быть протестирован идеально и всё равно вызываться из неправильной ветки.

package/ai/flow-sim/scenarios/S1-route-new-scope.md

@@ -0,0 +1,107 @@
+# S1 — новый product/library scope из чистого портала
+
+Проверяет: router `LOGIC_SWITCH` ветку 3 (`new-scope` + `product`/`library` → `scope.directive.xml`)
+на v2-репозитории с READINESS=ready и живым порталом.
+
+## Fixture
+
+`package.json`:
+
+```json
+{
+  "name": "demo-project",
+  "version": "0.1.0",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "gennady lint --all .",
+    "format": "prettier --check ."
+  }
+}
+```
+
+`node_modules/.bin/gennady` (пустой файл — гейт readiness проверяет только наличие):
+
+```
+
+```
+
+`specs/README.md`:
+
+````markdown
+# demo-project
+
+## Vision
+
+Набор личных инструментов продуктивности.
+
+## Scope Graph
+
+```mermaid
+graph TD
+  backend --> infra-base
+```
+````
+
+## Scopes
+
+| Scope                                           | Type           | Spec | Description                |
+| ----------------------------------------------- | -------------- | ---- | -------------------------- |
+| [`infra-base`](./infra-base/infra-base.spec.md) | infrastructure | ✅   | TS + vitest + gennady lint |
+| [`backend`](./backend/backend.spec.md)          | product        | ✅   | Backend API                |
+
+```
+
+Никакого `tasks/` каталога (v2), никакого `specs/.sdd-session.md` (нет сессии в процессе),
+никакого `specs/notes/` (scope ещё не существует).
+
+## Entry
+
+Скилл: `/sdd`. Первая реплика оператора:
+
+> Нужен новый scope: продукт `notes` — заметки с локальным хранением.
+
+## Operator Script
+
+1. На объединённый вопрос роутера (тип scope: product/library + предложенный `scale`) — ответ:
+   «product, со scale согласен» (принимает предложенный дефолт `scale`, явно называет `product`).
+2. На вопрос `scope.directive` STEP_1_CONFIRM (подтверждение scope-type + состав секций) — ответ:
+   «да, годится».
+
+## Stop
+
+Сразу после того, как `scope.directive` (mode=`greenfield`) показал Approval Check по итогам
+STEP_1_CONFIRM (подтверждён scope-type + список секций) и получил от оператора «да, годится».
+Прогон завершается ДО STEP_2_INTENT_CAPTURE — ничего из содержимого спеки ещё не пишется, интервью
+не запускается. Трейс заканчивается строкой `stop: per-map — <это условие дословно>` (не `halt:` —
+остановка по карте, не директивный `H_*`-гейт).
+
+## Checkpoints
+
+1. Первый вызов инструмента в трейсе — `sdd-state` (без `--probe`, без пути) — router STEP_0_STATE:
+   «Call `sdd-state` (deterministic) — one call returns everything routing needs».
+2. Сработавшая ветка `STEP_0_STATE` — `LogicSwitch` DEFAULT: «repo is `v2` + ready — proceed to
+   STEP_1_CLASSIFY» (никакая другая ветка STEP_0_STATE — ни `migration-v1-v2`, ни `readiness` — не
+   загружена; в трейсе нет строк `directive: ai/directives/sdd-v2/migration-v1-v2.directive.xml
+   loaded` или `directive: ai/directives/sdd-v2/readiness.directive.xml loaded`).
+3. `STEP_1_CLASSIFY` классифицировал intent как `new-scope`, зафиксировал scope-type = `product` и
+   `scale:` в `specs/.sdd-session.md` — до этого была ровно ОДНА объединённая развилка с оператором
+   («one stop for both, never a second one»).
+4. Сработавшая ветка `LOGIC_SWITCH` (главный роутинг) — дословно: «WHEN intent ∈ {new-scope,
+   evolve-scope} AND scope-type ∈ {product, library} -> READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/scope.directive.xml")».
+   В трейсе ровно один `directive: ... loaded` после router — `scope.directive.xml`; ни `infra`, ни
+   `interface`, ни `module`, ни `root`, ни `recover-from-code` директивы не загружены.
+5. Внутри `scope.directive`: `AX_MODE_AUTO_DETECT_OR_HALT` определил mode=`greenfield` (файла
+   `specs/notes/notes.spec.md` нет на диске) — не `refine`, не `pivot`.
+6. Прогон остановился на `STEP_1_CONFIRM`: «Confirm the scope-type, outline which sections the spec
+   will carry. Approval Check. STOP.» — нет ни одной строки `write:` под `specs/notes/` (запись
+   `specs/.sdd-session.md` предписана самим роутером на `STEP_1_CLASSIFY` и легальна — это не
+   создание артефакта scope, это фиксация сессии), `sdd-new product --scope notes` НЕ вызван (это
+   STEP_9, недостижим до стопа).
+7. На `STEP_1_CONFIRM` состав секций показан оператору как `show:`-строка, перечисляющая секции
+   именно из манифеста `sdd-new product --scope notes --manifest` (`SCOPE_TYPE`, `VISION`,
+   `OVERVIEW`, `PROJECT_TYPE`, `GOLDEN_DX`, `SCOPE_DEPENDENCIES`, `REQUIREMENTS_AND_CONSTRAINTS`,
+   `ARCHITECTURE`, `MODULE_MAP`, `DECISION_LOG`, `BOOTSTRAP_REQUIREMENTS`, `HANDOFF`) — включая
+   `OVERVIEW` и `MODULE_MAP` — а не произвольный пересказ секций агентом.
+```

package/ai/flow-sim/scenarios/S10-multi-scope-route.md

@@ -0,0 +1,213 @@
+# S10 — multi-scope изменение, роутинг в порядке Scope Graph
+
+Проверяет: router `STEP_1_CLASSIFY` (intent = `multi-scope`, обязательная объединённая SCALE-развилка)
+и `LOGIC_SWITCH` ветку `multi-scope` (`ai/directives/sdd-v2/router.directive.xml`) — декомпозицию
+запроса по Scope Graph в порядке зависимостей (`AX_CROSS_SCOPE_CHANGE`: shared-scope первым) на
+v2-репозитории с READINESS=ready и живым порталом, где оба затронутых scope уже имеют спеку.
+
+## Fixture
+
+Ниже `<GENNADY_WORKTREE>` — абсолютный путь к worktree gennady, который выдаёт оркестратор. Все
+`tool:`-вызовы gennady-команд в Checkpoints (`sdd-state`, `orient`, `sdd-check`, …) — сокращение для
+`npx tsx <GENNADY_WORKTREE>/cli/gennady.ts <cmd> <args>`, НЕ `gennady <cmd>` напрямую и НЕ чужой
+чекаут `~/Developer/gennady` (per `PROTOCOL.md`, «Правила исполнителя»).
+
+`package.json` (`typecheck`/`test`/`test:coverage`/`format` — инструментарий demo-фикстуры, не
+вызываются ни в одном Checkpoint этой карты; `lint` — реальная gennady-команда, поэтому
+репо-относительно):
+
+```json
+{
+  "name": "demo-project",
+  "version": "0.1.0",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "npx tsx <GENNADY_WORKTREE>/cli/gennady.ts lint --all .",
+    "format": "prettier --check ."
+  }
+}
+```
+
+`node_modules/.bin/gennady` (пустой файл — гейт readiness проверяет только наличие):
+
+```
+
+```
+
+`specs/README.md`:
+
+````markdown
+# demo-project
+
+## Vision
+
+Набор личных инструментов продуктивности с общим слоем контрактов.
+
+## Scope Graph
+
+```mermaid
+graph TD
+  contracts --> infra-base
+  app --> infra-base
+  app --> contracts
+```
+
+## Scopes
+
+| Scope                                           | Type           | Spec | Description                       |
+| ----------------------------------------------- | -------------- | ---- | --------------------------------- |
+| [`infra-base`](./infra-base/infra-base.spec.md) | infrastructure | ✅   | TS + vitest + gennady lint        |
+| [`contracts`](./contracts/contracts.spec.md)    | library        | ✅   | Общие типы и контракты            |
+| [`app`](./app/app.spec.md)                      | product        | ✅   | Приложение, потребитель contracts |
+````
+
+`specs/contracts/contracts.spec.md` (минимальная существующая спека — содержимое не читается до
+`## Stop`, только факт присутствия файла имеет значение для mode-detection):
+
+```markdown
+# contracts
+
+## Vision
+
+Общий пакет типов и контрактов для всех продуктовых scope.
+
+## Requirements and Constraints
+
+- Тип `Session` — сессия пользователя.
+```
+
+`specs/app/app.spec.md` (минимальная существующая спека, тем же принципом):
+
+```markdown
+# app
+
+## Vision
+
+Основное приложение, использует `contracts` для типов домена.
+
+## Scope Dependencies
+
+- `contracts` — типы домена (`Session` и производные).
+```
+
+Никакого `tasks/` каталога (v2), никакого `specs/.sdd-session.md` (нет сессии в процессе),
+никакого `specs/notes/` или прочих незарегистрированных scope.
+
+Реестр правил — четыре директории-болванки, по одному минимальному файлу в каждой (per
+`AX_SCOPE_RULES_DECLARATION`-категории `coding`/`testing`/`architecture`/`infra`:
+`ai/directives/<category>/<rule>.xml`),
+чтобы ЛЮБОЕ чтение реестра правил в этом прогоне (даже если по тексту карты оно не должно быть
+достигнуто до `## Stop`) находило файл внутри песочницы фикстуры, а не утекало в
+`ai/directives/coding/` etc. реального `<worktree>` (запрещено `PROTOCOL.md`: «Реестр правил и любые
+файлы проекта читать ТОЛЬКО внутри песочницы фикстуры»):
+
+`ai/directives/coding/typescript-rules.xml`:
+
+```xml
+<Rule id="TS_BASE" type="coding"><Text>Строгий TypeScript, без `any`.</Text></Rule>
+```
+
+`ai/directives/testing/vitest-rules.xml`:
+
+```xml
+<Rule id="VITEST_BASE" type="testing"><Text>Тесты — `vitest run`, coverage — `vitest run --coverage`.</Text></Rule>
+```
+
+`ai/directives/architecture/module-rules.xml`:
+
+```xml
+<Rule id="MODULE_BASE" type="architecture"><Text>Модуль = Port + Adapter, без прямых импортов между модулями.</Text></Rule>
+```
+
+`ai/directives/infra/lint-rules.xml`:
+
+```xml
+<Rule id="LINT_BASE" type="infra"><Text>`gennady lint --all .` — без предупреждений.</Text></Rule>
+```
+
+## Entry
+
+Скилл: `/sdd`. Первая реплика оператора:
+
+> Добавь поле `expiresAt` в тип `Session` в `contracts` и обнови `app`, который его использует.
+
+## Operator Script
+
+1. На объединённый вопрос роутера (`STEP_1_CLASSIFY`: intent = multi-scope + предложенный `scale`
+   default) — ответ: «да, multi-scope, scale — module, согласен» (принимает classification и
+   предложенный дефолт `scale` одним ответом, одна развилка на обоих).
+
+Примечание: «brief check-in with the operator between scopes» (LOGIC_SWITCH, ветка `multi-scope`)
+в этой карте НЕ достигается — прогон останавливается внутри обработки ПЕРВОГО scope (`contracts`),
+до того как для него завершится собственная ветка LOGIC_SWITCH и наступит переход ко второму
+scope (`app`). Более тяжёлый Stop (после завершения scope 1) требовал бы полного approval-обмена
+`scope.directive` STEP_1_CONFIRM — карта намеренно дешёвая и стопится раньше.
+
+## Stop
+
+Сразу после того, как `scope.directive.xml` (для ПЕРВОГО scope в порядке Scope Graph — `contracts`,
+mode=`refine`, т.к. `specs/contracts/contracts.spec.md` уже существует на диске) был загружен и
+прошёл `STEP_0_INTAKE` (mode-detect), — но ДО того, как его собственный `STEP_1_CONFIRM` задал
+Approval Check оператору. Прогон завершается ДО STEP*1_CONFIRM's question — никакого вопроса про
+`contracts` ещё не задано, `app` ещё не тронут вообще (ни `directive: ... scope.directive.xml
+loaded` во второй раз, ни `note: cross-scope loop 2/2` в трейсе нет). Трейс заканчивается строкой
+`stop: per-map — <это условие дословно>` (не `halt:` — остановка по карте, не директивный
+`H*\*`-гейт).
+
+## Checkpoints
+
+1. Первый вызов инструмента в трейсе — `sdd-state` (без `--probe`, без пути) — router
+   `STEP_0_STATE`: «Call `sdd-state` (deterministic) — one call returns everything routing needs».
+2. Сработавшая ветка `STEP_0_STATE` — `LogicSwitch` DEFAULT: «repo is `v2` + ready — proceed to
+   STEP_1_CLASSIFY» (никакая другая ветка STEP_0_STATE — ни `migration-v1-v2`, ни `readiness` — не
+   загружена; в трейсе нет строк `directive: ai/directives/sdd-v2/migration-v1-v2.directive.xml
+loaded` или `directive: ai/directives/sdd-v2/readiness.directive.xml loaded`).
+3. `STEP_1_CLASSIFY` классифицировал intent как `multi-scope` строго на основании текста: «A change
+   spanning several scopes (cross-platform) is normal (`AX_CROSS_SCOPE_CHANGE`): open a working set
+   of the touched specs in the session and route them in Scope-Graph dependency order — the shared /
+   cross-cutting scope first, then its dependents — looping the per-scope branches, not a new
+   branch.» — рабочий набор в `specs/.sdd-session.md` содержит ОБЕ затронутых спеки (`contracts` и
+   `app`), не одну.
+4. До routing — ровно ОДНА объединённая развилка с оператором (intent + SCALE), а не две отдельные:
+   `STEP_1_CLASSIFY` дословно: «present the proposed SCALE together with the classified intent as a
+   pre-filled default the operator confirms or corrects, in the SAME exchange that resolves any
+   intent ambiguity — one stop for both, never a second one.» В трейсе ровно одна строка `ask:` /
+   `operator:` до `step: STEP_2_ROUTE`.
+5. Эта развилка — обязательный именованный hard stop, не пропущенный из-за уверенности классификации
+   (интент был читаем прямо из сообщения оператора): `STEP_1_CLASSIFY` дословно: «This exchange is
+   mandatory even when the intent is unambiguous from state and the scale does not change the route
+   — it is a named hard stop (`AX_DIALOGUE_DISCIPLINE`), never skipped on high confidence.» —
+   Checkpoint нарушен, если в трейсе нет строки `ask:`/`operator:` для этого шага (агент «угадал» и
+   молча записал `scale:` без вопроса).
+6. Сработавшая ветка `LOGIC_SWITCH` (главный роутинг, router `STEP_2_ROUTE`) — дословно: «WHEN intent
+   = multi-scope (one change spans several scopes) -> decompose the request against the Scope Graph
+   in dependency order per `AX_CROSS_SCOPE_CHANGE` (the shared / cross-cutting scope first, then its
+   dependents); for EACH scope in that order run its own ordinary route (branches 3–6 of this same
+   LOGIC_SWITCH) to completion, one scope at a time, with a brief check-in with the operator between
+   scopes» — ни одна другая ветка `LOGIC_SWITCH` (`root`, `recover-from-code`, `infra`, `interface`,
+   `module`, DEFAULT) не сработала на верхнем уровне.
+7. Порядок обработки — `contracts` (зависимость) ПЕРВЫМ, `app` (потребитель) вторым, никогда наоборот
+   — по `AX_CROSS_SCOPE_CHANGE`: «So author the shared scope FIRST, then detail each dependent scope
+   — the order is the Scope Graph's dependency order (a dependency is authored before its
+   dependents).» В трейсе строка `note: cross-scope loop 1/2 — scope=contracts` предшествует любой
+   обработке `app`; строки `note: cross-scope loop 2/2 — scope=app` в трейсе НЕТ вообще (прогон
+   стопится внутри обработки scope 1, см. `## Stop`).
+8. Для scope `contracts` сработавшая под-ветка LOGIC_SWITCH (branch 3, «run its own ordinary route»)
+   — дословно: «WHEN intent ∈ {new-scope, evolve-scope} AND scope-type ∈ {product, library} ->
+   READ_AND_USE_DIRECTIVE("ai/directives/sdd-v2/scope.directive.xml")» — ни `infra`, ни `interface`,
+   ни `module`, ни `root`, ни `recover-from-code` директивы не загружены; в трейсе ровно один
+   `directive: ai/directives/sdd-v2/scope.directive.xml loaded` (для `contracts`; для `app` вторая
+   загрузка не достигнута до Stop).
+9. Внутри `scope.directive` (для `contracts`): `STEP_0_INTAKE` определил mode = `refine`, не
+   `greenfield` — файл `specs/contracts/contracts.spec.md` присутствует на диске, что по тексту
+   STEP_0_INTAKE («Stat `specs/<scope>/<scope>.spec.md`: absent → `greenfield`; present → detect the
+   mode per `AX_DIRECTIVE_MODE` / `AX_MODE_AUTO_DETECT_OR_HALT`») обязывает detect-the-mode, а не
+   молчаливый дефолт на greenfield.
+10. Прогон остановился ДО вопроса `STEP_1_CONFIRM` scope.directive для `contracts`: «Confirm the
+    scope-type, outline which sections the spec will carry. Approval Check. STOP.» — в трейсе нет ни
+    одной строки `ask:`/`operator:` после `step: STEP_1_CONFIRM` этого вложенного вызова, нет ни
+    одной строки `write:` под `specs/contracts/` или `specs/app/` (обновление `.sdd-session.md` на
+    `STEP_1_CLASSIFY` router — легально, это фиксация сессии, не артефакт scope), `sdd-new` не
+    вызван ни для одного из scope.