@nitra/cursor 3.21.1 → 3.23.0

package/scripts/dispatcher/lib/docs/state-store.md

@@ -0,0 +1,303 @@
+# state-store.mjs
+
+## Огляд
+
+Модуль `state-store.mjs` реалізує **crash-safe сховище runtime-стану `flow`** (відповідно до spec §4 та §4.1 правила `n-flow`). Він зберігає поточний стан виконання worktree-флоу у вигляді JSON-файла, гарантує атомарність запису та fail-closed поведінку при пошкодженні даних.
+
+Ключові архітектурні рішення:
+
+- **Sibling-файл, а не файл усередині worktree.** Файл стану розміщується **поруч** із checkout-директорією worktree, а не всередині неї. Для checkout-директорії `…/.worktrees/feat-x` файл стану — `…/.worktrees/feat-x.flow.json`. Причина: файл усередині worktree був би `untracked` у feature-гілці й міг би випадково потрапити у `git add -A`.
+- **Атомарний запис** — через temp-файл на тому самому файловому системному рівні, `fsync` даних і атомарний `rename` (POSIX-гарантія: операція або повністю успішна, або не відбулась).
+- **Fail-closed на corruption** — будь-яка некоректність (невалідний JSON, несумісний `schema_version`) призводить до `throw`, а не до тихого скидання стану. Принцип: краще зупинити flow, ніж стартувати новий поверх зіпсованого стану.
+- **WAL-перехід** — пара `appendEvent` (журнал) → `updateState` (snapshot). Журнал — джерело істини для reconcile при `resume`, snapshot — швидкий зріз поточного стану.
+- **Усі шляхи абсолютні** — вимога правила `no-relative-fs-path`. Кожна публічна функція робить `isAbsolute()`-перевірку й кидає, якщо їй передали відносний шлях.
+
+## Експорти / API
+
+| Експорт                                                             | Тип                    | Призначення                                                                              |
+| ------------------------------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------- |
+| `SCHEMA_VERSION`                                                    | `const number` (= `1`) | Поточна версія схеми JSON-стану. Несумісність → fail-closed read.                        |
+| `flowStatePath(worktreeDir)`                                        | function               | Дериватор шляху sibling-файла стану з абсолютного шляху worktree-checkout.               |
+| `writeState(statePath, state)`                                      | function               | Атомарний запис стану з автоматичним проставленням `schema_version`.                     |
+| `readState(statePath)`                                              | function               | Читання стану з валідацією `schema_version`; `null`, якщо файлу нема.                    |
+| `updateState(statePath, fn)`                                        | function               | Read-modify-write: читає, прогонить через трансформер `fn`, атомарно пише.               |
+| `removeState(statePath)`                                            | function               | Ідемпотентне видалення sibling-файла стану.                                              |
+| `recordTransition({ statePath, eventsPath }, event, stateFn, now?)` | function               | WAL-перехід: спершу `appendEvent`, потім `updateState`.                                  |
+| `cleanupFlowSiblings(worktreeDir)`                                  | function               | Видалення всіх runtime-sibling-ів worktree (`.flow.json`, `.events.jsonl`, лок-каталог). |
+
+## Функції
+
+### `flowStatePath(worktreeDir)`
+
+**Сигнатура:** `(worktreeDir: string) => string`
+
+**Параметри:**
+
+- `worktreeDir` — абсолютний шлях checkout-директорії worktree (наприклад, `…/.worktrees/feat-x`).
+
+**Повертає:** Абсолютний шлях sibling-файла стану виду `…/.worktrees/feat-x.flow.json`.
+
+**Логіка:** Бере `dirname(worktreeDir)` (батьківську теку, як правило `.worktrees/`) і конкатенує з `basename(worktreeDir) + '.flow.json'`.
+
+**Помилки:** `Error('flowStatePath: очікується абсолютний шлях …')` — якщо `worktreeDir` не абсолютний.
+
+**Side effects:** Немає (чиста функція над шляхами).
+
+---
+
+### `fsyncPath(path)` (внутрішня)
+
+**Сигнатура:** `(path: string) => void`
+
+**Параметри:**
+
+- `path` — абсолютний шлях до файла або каталогу, який треба `fsync`-нути.
+
+**Повертає:** `void`.
+
+**Логіка:** Відкриває файл/каталог у режимі читання (`openSync(path, 'r')`), викликає `fsyncSync(fd)`, у `finally` закриває дескриптор через `closeSync`.
+
+**Side effects:** Системний виклик `fsync` — гарантує, що дані файла записані на фізичний носій (необхідно перед `rename`, щоб уникнути ситуації, коли rename видно, а вміст ще в буфері).
+
+**Примітка:** Функція приватна (не експортується), використовується лише `writeState`.
+
+---
+
+### `writeState(statePath, state)`
+
+**Сигнатура:** `(statePath: string, state: object) => object`
+
+**Параметри:**
+
+- `statePath` — абсолютний шлях кінцевого файла стану (`.flow.json`).
+- `state` — об'єкт стану **без** поля `schema_version` (воно проставляється автоматично).
+
+**Повертає:** Фактично записаний об'єкт виду `{ schema_version: SCHEMA_VERSION, ...state }`.
+
+**Алгоритм (атомарний запис):**
+
+1. Перевірка абсолютності шляху → `throw`, якщо відносний.
+2. `mkdirSync(dir, { recursive: true })` — гарантуємо існування батьківської теки.
+3. Збираємо `payload = { schema_version: SCHEMA_VERSION, ...state }`.
+4. Генеруємо унікальне ім'я temp-файла: `.${basename(statePath)}.${pid}.${randomHex6}.tmp` у тій самій теці (важливо — той самий FS, щоб `rename` був атомарним).
+5. `writeFileSync(tmp, JSON.stringify(payload, null, 2) + '\n', 'utf8')`.
+6. `fsyncPath(tmp)` — flush даних temp-файла на диск.
+7. `renameSync(tmp, statePath)` — атомарна заміна.
+8. Best-effort `fsyncPath(dir)` — fsync батьківського каталогу для durability rename. На Windows може кинути `EISDIR`/`EPERM` — помилка проковтується (некритично).
+
+**Помилки:** `Error('writeState: очікується абсолютний шлях …')` — якщо `statePath` не абсолютний. Інші помилки I/O (нема прав, диск повний тощо) пробрасуються нагору.
+
+**Side effects:**
+
+- Створення батьківської теки (якщо її нема).
+- Створення й видалення temp-файла з PID та випадковим суфіксом.
+- Перейменування `tmp → statePath`.
+- `fsync` файла та (best-effort) каталогу.
+
+---
+
+### `readState(statePath)`
+
+**Сигнатура:** `(statePath: string) => object | null`
+
+**Параметри:**
+
+- `statePath` — абсолютний шлях `.flow.json`.
+
+**Повертає:**
+
+- `null`, якщо файлу не існує (нормальна ситуація: flow ще не починався).
+- Розпарсений об'єкт стану — за успішного читання й валідації.
+
+**Алгоритм:**
+
+1. Перевірка абсолютності шляху.
+2. `existsSync(statePath)` → `false` → повертаємо `null`.
+3. `readFileSync(statePath, 'utf8')`.
+4. Спроба `JSON.parse(raw)`; якщо `SyntaxError` → `throw` з повідомленням `пошкоджений стан (невалідний JSON) … fail-closed`.
+5. Валідація типу й `schema_version`: якщо не об'єкт, `null`, або `schema_version !== SCHEMA_VERSION` → `throw` `несумісний або пошкоджений schema_version … fail-closed`.
+6. Повертаємо розпарсений об'єкт.
+
+**Помилки:**
+
+- `Error('readState: очікується абсолютний шлях …')`.
+- `Error('readState: пошкоджений стан (невалідний JSON) … fail-closed')` (§4.1.6).
+- `Error('readState: несумісний або пошкоджений schema_version … fail-closed')` (§4.1.6).
+
+**Side effects:** Тільки читання файла (без модифікацій).
+
+---
+
+### `updateState(statePath, fn)`
+
+**Сигнатура:** `(statePath: string, fn: (state: object) => object) => object`
+
+**Параметри:**
+
+- `statePath` — абсолютний шлях `.flow.json`.
+- `fn` — функція-трансформер: приймає поточний стан (або `{}`, якщо файла нема) і повертає новий стан.
+
+**Повертає:** Записаний об'єкт (результат `writeState`).
+
+**Алгоритм:**
+
+1. `current = readState(statePath)`.
+2. `next = fn(current ?? {})` — якщо файла не існує, `fn` отримує порожній об'єкт.
+3. `return writeState(statePath, next)`.
+
+**Помилки:** Будь-яке пробивання з `readState` чи `writeState`. Окрім того, помилки всередині `fn` пробросяться як є.
+
+**Side effects:** Read-modify-write — повний цикл (читання → трансформ → атомарний запис).
+
+---
+
+### `removeState(statePath)`
+
+**Сигнатура:** `(statePath: string) => void`
+
+**Параметри:**
+
+- `statePath` — абсолютний шлях `.flow.json`.
+
+**Повертає:** `void`.
+
+**Алгоритм:** `rmSync(statePath, { force: true })` — ідемпотентно (відсутній файл не помилка).
+
+**Помилки:** `Error('removeState: очікується абсолютний шлях …')`.
+
+**Side effects:** Видалення sibling-файла стану.
+
+**Контекст використання:** Cleanup при `worktree remove` або `flow cancel`.
+
+---
+
+### `recordTransition({ statePath, eventsPath }, event, stateFn, now?)`
+
+**Сигнатура:** `({ statePath: string, eventsPath: string }, event: object, stateFn: (state: object) => object, now?: () => number) => object`
+
+**Параметри:**
+
+- `paths.statePath` — абсолютний шлях `.flow.json`.
+- `paths.eventsPath` — абсолютний шлях журналу подій `.events.jsonl`.
+- `event` — об'єкт події переходу (формат визначається `appendEvent`).
+- `stateFn` — трансформер стану (як у `updateState`).
+- `now` — фабрика поточного часу в ms (за замовчуванням `Date.now`); використовується для тестів.
+
+**Повертає:** Записаний стан (результат `updateState`).
+
+**Алгоритм (WAL-перехід, §4.1.2):**
+
+1. `appendEvent(eventsPath, event, now)` — спершу **журнал** (durable WAL-запис події).
+2. `updateState(statePath, stateFn)` — потім snapshot.
+
+**Гарантія:** Якщо крок 2 впаде, подія в журналі вже durable; на `resume` reconcile-логіка зможе відновити стан зі snapshot + хвоста журналу.
+
+**Side effects:** Дописування в `.events.jsonl` та атомарний read-modify-write `.flow.json`.
+
+---
+
+### `cleanupFlowSiblings(worktreeDir)`
+
+**Сигнатура:** `(worktreeDir: string) => void`
+
+**Параметри:**
+
+- `worktreeDir` — абсолютний шлях checkout-директорії worktree (`…/.worktrees/feat-x`).
+
+**Повертає:** `void`.
+
+**Алгоритм:** Для `base = basename(worktreeDir)` та `dir = dirname(worktreeDir)` видаляє:
+
+1. `<dir>/<base>.flow.json` — sibling-snapshot стану.
+2. `<dir>/<base>.events.jsonl` — sibling-журнал подій.
+3. `<dir>/.flow-lock-<base>/` — лок-каталог (з `recursive: true`).
+
+Усі `rmSync` з `force: true` — ідемпотентні.
+
+**Помилки:** `Error('cleanupFlowSiblings: очікується абсолютний шлях …')`.
+
+**Side effects:** Видалення трьох sibling-артефактів. Викликається з `flow cancel` та `worktree remove`. Інакше sibling-и осиротіють — git їх не чистить (бо вони поза worktree).
+
+## Залежності
+
+### Node.js stdlib
+
+- `node:fs` — `closeSync`, `existsSync`, `fsyncSync`, `mkdirSync`, `openSync`, `readFileSync`, `renameSync`, `rmSync`, `writeFileSync`.
+- `node:path` — `basename`, `dirname`, `isAbsolute`, `join`.
+- `node:crypto` — `randomBytes` (унікальне ім'я temp-файла).
+- `node:process` — `pid` (також для унікальності temp-імені, особливо при паралельних процесах).
+
+### Внутрішні залежності модуля
+
+- `./events.mjs` — функція `appendEvent(eventsPath, event, now)`. Використовується лише в `recordTransition`.
+
+### Логічні залежності (через дизайн, не через `import`)
+
+- Spec `n-flow` §4, §4.1, §4.1.2, §4.1.6 — формальні вимоги до crash-safety та fail-closed.
+- Конвенція розміщення worktree: усі worktree під `.worktrees/<branch>/`; sibling-файли — на одному рівні з checkout.
+
+## Потік виконання / Використання
+
+### Типовий життєвий цикл стану flow
+
+```
+1. Старт flow:
+   const statePath = flowStatePath('/abs/path/.worktrees/feat-x')
+   //   → '/abs/path/.worktrees/feat-x.flow.json'
+
+2. Перший запис (initial state):
+   writeState(statePath, { stage: 'init', step: 0 })
+   //   → файл містить { schema_version: 1, stage: 'init', step: 0 }
+
+3. Перехід стану з журналюванням (WAL):
+   recordTransition(
+     { statePath, eventsPath: statePath.replace('.flow.json', '.events.jsonl') },
+     { type: 'stage_advanced', from: 'init', to: 'apply' },
+     (s) => ({ ...s, stage: 'apply', step: s.step + 1 })
+   )
+
+4. Read-modify-write без події (рідко):
+   updateState(statePath, (s) => ({ ...s, last_seen_at: Date.now() }))
+
+5. Читання при resume:
+   const state = readState(statePath)
+   if (state === null) { /* новий flow */ }
+   else { /* відновлення з state */ }
+
+6. Cleanup на завершення / cancel:
+   cleanupFlowSiblings('/abs/path/.worktrees/feat-x')
+   // → видалить feat-x.flow.json, feat-x.events.jsonl, .flow-lock-feat-x/
+```
+
+### Гарантії crash-safety
+
+- **Crash під час `writeFileSync(tmp, …)`** — кінцевий файл `statePath` залишається попередньою версією; temp-файл — orphan (буде перезаписаний при наступному запуску завдяки `pid + randomBytes`).
+- **Crash між `writeFileSync` і `fsyncPath(tmp)`** — temp-файл може бути порожнім/частковим, але `rename` ще не виконано — `statePath` цілий.
+- **Crash між `fsyncPath(tmp)` і `renameSync`** — temp-файл цілий і durable, але не на місці; `statePath` цілий.
+- **Crash під час `renameSync`** — POSIX гарантує атомарність: або `statePath` — старий вміст, або новий, **ніколи частковий**.
+- **Crash після `renameSync` до fsync каталогу** — на більшості FS rename вже durable; fsync каталогу — best-effort страховка.
+
+### Fail-closed reading
+
+При `readState`:
+
+- **Файл порожній / не JSON** → `throw 'пошкоджений стан (невалідний JSON) … fail-closed'`. Адмін має вручну інспектувати журнал подій та прийняти рішення (replay або видалення).
+- **`schema_version` відсутня / інша** → `throw 'несумісний або пошкоджений schema_version … fail-closed'`. Захищає від запуску нової версії dispatcher над станом старого формату й навпаки.
+
+### Контекст у dispatcher
+
+Модуль є інфраструктурною частиною `npm/scripts/dispatcher/`. Виклики йдуть із вищих шарів (стейт-машини flow, CLI-команди `flow start/resume/cancel`, обробники сигналів). Модуль сам не керує життєвим циклом — він лише надає примітиви read/write/update/remove/transition та шляхові деривації.
+
+## Rebuild Test
+
+Документація містить достатньо інформації, щоб відновити функціональність модуля з нуля:
+
+- Точні імпорти з Node stdlib та локального `./events.mjs`.
+- Константу `SCHEMA_VERSION = 1`.
+- Сім публічних функцій з повними сигнатурами, валідацією аргументів, алгоритмами та повідомленнями про помилки.
+- Внутрішню helper-функцію `fsyncPath` зі сценарієм використання.
+- Точну схему атомарного запису (temp у тій самій теці → write → fsync → rename → best-effort fsync каталогу).
+- Точну схему fail-closed reading (`null` для відсутнього файла, throw для пошкодженого/несумісного).
+- WAL-послідовність `appendEvent` → `updateState` у `recordTransition`.
+- Перелік усіх трьох sibling-артефактів для `cleanupFlowSiblings` (`.flow.json`, `.events.jsonl`, `.flow-lock-<base>/`).
+- Дериватор `flowStatePath`: `join(dirname(worktreeDir), basename(worktreeDir) + '.flow.json')`.

package/scripts/dispatcher/lib/docs/subagent-runner.md

@@ -0,0 +1,173 @@
+# subagent-runner.mjs
+
+## Огляд
+
+`subagent-runner.mjs` — модуль абстракції спавну сфокусованого субагента для Активного Раннера (фаза Ф3/Ф4 диспетчера). Реалізує специфікацію §15.1: надає уніфікований інтерфейс `runStep(prompt, opts)` поверх трьох можливих backend-ів:
+
+1. `claude-agent-sdk` — програмний доступ через пакет `@anthropic-ai/claude-agent-sdk`, потребує змінної середовища `ANTHROPIC_API_KEY`.
+2. `claude -p` — CLI-аутентифікація користувача через виконуваний `claude` у `PATH`.
+3. `cursor-agent -p` — CLI-аутентифікація через виконуваний `cursor-agent` у `PATH`.
+
+Якщо жоден backend недоступний — модуль кидає виняток із текстом `NO_BACKEND` (polyfill без runner-а не стартує, §2.2).
+
+Згідно з коментарем у заголовку файлу, для inner-спавну навмисно НЕ використовується pi.dev: у автономному режимі pi.dev — це зовнішній драйвер, тож спавнити ним внутрішні субагенти призвело б до рекурсії (§9.1).
+
+Усі probe-залежності (`spawn`, `isInPath`, `canImportSdk`, `query`) проектовані під ін'єкцію — для тестування без реальних процесів та без встановленого SDK.
+
+## Експорти / API
+
+Модуль експортує чотири іменовані функції:
+
+- `isBinaryInPath(name, spawn?)` — перевірка наявності бінарника в `PATH`.
+- `selectBackend({ hasApiKey, canImportSdk, isInPath })` — вибір backend-а за пріоритетом.
+- `cliRunner(bin, deps?)` — фабрика runner-а для CLI-варіанту.
+- `sdkRunner(deps?)` — фабрика runner-а для SDK-варіанту.
+- `createRunner(deps?)` — головний фасад, що сам визначає та повертає потрібний runner.
+
+Внутрішня (не експортована) функція: `probeSdk()` — перевіряє можливість динамічного імпорту SDK.
+
+Константа модульного рівня `NO_BACKEND` — текст повідомлення помилки, коли жоден backend недоступний.
+
+## Функції
+
+### `isBinaryInPath(name, spawn = spawnSync)`
+
+Перевіряє, чи є виконуваний бінарник у `PATH` через виклик `command -v <name>`.
+
+- Параметри:
+  - `name` (`string`) — ім'я виконуваного.
+  - `spawn` (`typeof spawnSync`, optional) — ін'єкція для тестів; за замовчуванням `spawnSync` із `node:child_process`.
+- Повертає: `boolean` — `true`, якщо `spawn` повернув статус `0`; інакше `false`. Якщо `r.status` дорівнює `null`/`undefined`, трактується як `1` (тобто `false`).
+- Side effects: виклик дочірнього процесу `command -v` через shell (`shell: true`).
+
+### `selectBackend({ hasApiKey, canImportSdk, isInPath })`
+
+Вибирає backend за чітко зафіксованим пріоритетом: SDK > Claude CLI > Cursor CLI.
+
+- Параметри (один об'єкт):
+  - `hasApiKey` (`boolean`) — чи задана `ANTHROPIC_API_KEY`.
+  - `canImportSdk` (`boolean`) — чи імпортується `@anthropic-ai/claude-agent-sdk`.
+  - `isInPath` (`(name: string) => boolean`) — предикат наявності бінарника у `PATH`.
+- Повертає: рядковий літерал `'sdk'`, `'claude'`, `'cursor'` або `null`.
+- Логіка:
+  1. Якщо `hasApiKey` і `canImportSdk` одночасно істинні — `'sdk'`.
+  2. Інакше якщо `isInPath('claude')` — `'claude'`.
+  3. Інакше якщо `isInPath('cursor-agent')` — `'cursor'`.
+  4. Інакше — `null`.
+- Side effects: відсутні (за умови, що `isInPath` чистий).
+
+### `cliRunner(bin, deps = {})`
+
+Створює CLI-runner на основі бінарника `claude` або `cursor-agent` (обидва підтримують прапор `-p` для подачі промпта зі stdin).
+
+- Параметри:
+  - `bin` (`'claude' | 'cursor-agent'`) — який саме CLI запускати.
+  - `deps.spawn` (`typeof spawnSync`, optional) — ін'єкція; за замовчуванням `spawnSync`.
+- Повертає об'єкт:
+  - `backend` — рядок, що дорівнює переданому `bin`.
+  - `runStep(prompt, { cwd } = {})` — синхронна функція, що викликає `spawn(bin, ['-p'], { input: prompt, cwd, encoding: 'utf8' })`. Повертає `{ ok: boolean, output: string }`, де:
+    - `ok` — `true`, якщо `r.status === 0` (null/undefined трактується як 1 → `false`).
+    - `output` — конкатенація `stdout` та `stderr` (порожні рядки, якщо undefined).
+- Side effects: спавн дочірнього CLI-процесу при кожному виклику `runStep`.
+
+### `sdkRunner(deps = {})`
+
+Створює SDK-runner, який працює через async-iterable `query` з пакета `@anthropic-ai/claude-agent-sdk`.
+
+- Параметри:
+  - `deps.query` (`(input: object) => AsyncIterable`, optional) — ін'єкція функції `query` для тестів. Якщо не задано — модуль динамічно імпортує `@anthropic-ai/claude-agent-sdk` і бере звідти `query`.
+- Повертає об'єкт:
+  - `backend` — рядок `'sdk'`.
+  - `runStep(prompt, { cwd } = {})` — `async` функція, що повертає `Promise<{ ok: boolean, output: string }>`.
+- Логіка `runStep`:
+  1. Лінива ініціалізація `query` (якщо не передано в `deps`).
+  2. Виклик `query({ prompt, options: { cwd, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] } })`.
+  3. Ітерує асинхронно по повідомленнях:
+     - Якщо `msg.text` — рядок, додає його до `output`.
+     - Якщо `msg.type === 'result'`, фіналізує `ok = msg.is_error !== true`.
+  4. У разі винятку — повертає `{ ok: false, output: String(error?.message ?? error) }`.
+- Side effects: динамічний імпорт SDK (один раз на виклик, якщо `query` не ін'єктовано); мережеві/процесні дії SDK; обмеження інструментів виключно до `Read`, `Edit`, `Bash`.
+
+### `createRunner(deps = {})`
+
+Головний фасад модуля. Підбирає та повертає runner відповідно до доступних backend-ів.
+
+- Параметри (об'єкт `deps` для тестів; усі поля опціональні):
+  - `backend` — явне переозначення вибору (`'sdk'`/`'claude'`/`'cursor'`).
+  - `env` — мапа змінних середовища; за замовчуванням `processEnv` (`process.env`).
+  - `isInPath` — функція; за замовчуванням обгортка над `isBinaryInPath(name, deps.spawn)`.
+  - `canImportSdk` — заздалегідь обчислений прапор; інакше викликається `probeSdk()`.
+  - `spawn` — використовується як `deps.spawn` для дефолтного `isInPath`.
+  - `query` — пробрасується в `sdkRunner` як `deps.query`.
+- Повертає: `Promise<runner>`, де `runner` має форму `{ backend, runStep }` (синхронний для CLI, асинхронний для SDK — обидва типи представлені в одному фасаді).
+- Логіка:
+  1. Резолвить `env`, `isInPath`, `canImportSdk`.
+  2. Якщо `deps.backend` не задано — викликає `selectBackend({ hasApiKey: Boolean(env.ANTHROPIC_API_KEY), canImportSdk, isInPath })`.
+  3. Якщо backend усе ще `null`/falsy — `throw new Error(NO_BACKEND)`.
+  4. Для `'sdk'` — повертає `sdkRunner(deps)`.
+  5. Для `'claude'` — повертає `cliRunner('claude', deps)`.
+  6. Для будь-якого іншого ненульового — повертає `cliRunner('cursor-agent', deps)` (тобто `'cursor'` мапиться на `cursor-agent`).
+- Side effects: можливий динамічний імпорт SDK через `probeSdk()`; виклики `spawn` через дефолтний `isInPath`.
+
+### `probeSdk()` (внутрішня)
+
+Перевіряє, чи можна динамічно імпортувати `@anthropic-ai/claude-agent-sdk`.
+
+- Параметри: відсутні.
+- Повертає: `Promise<boolean>` — `true`, якщо `import` успішний, інакше `false` (виняток поглинається порожнім `catch`).
+- Side effects: динамічний `import()` модуля SDK.
+
+## Залежності
+
+- `node:child_process` — `spawnSync` (синхронний спавн дочірніх процесів для `command -v` та CLI-runner-а).
+- `node:process` — `env` як `processEnv` (читання змінних середовища, передусім `ANTHROPIC_API_KEY`).
+- `@anthropic-ai/claude-agent-sdk` (optional, динамічний `import`) — джерело функції `query` для SDK-runner-а; відсутність пакета — допустимий сценарій (`probeSdk()` ловить виняток).
+
+Зовнішні виконувані файли, очікувані у `PATH`:
+
+- `command` — POSIX-shell builtin для `command -v`.
+- `claude` — CLI Claude Code.
+- `cursor-agent` — CLI Cursor Agent.
+
+Жодних інших імпортів із локального проєкту модуль не робить — він самодостатній.
+
+## Потік виконання / Використання
+
+Типовий сценарій використання у диспетчері (Активний Раннер, фази Ф3/Ф4):
+
+1. Виклик `await createRunner()` без параметрів.
+2. Усередині `createRunner` виконується probe доступних backend-ів:
+   - перевіряється `process.env.ANTHROPIC_API_KEY`;
+   - намагається динамічно імпортувати `@anthropic-ai/claude-agent-sdk`;
+   - перевіряються `claude` та `cursor-agent` у `PATH` через `command -v`.
+3. `selectBackend` повертає перший доступний backend за пріоритетом SDK → claude → cursor.
+4. Якщо нічого не знайдено — кидається `Error(NO_BACKEND)`, що зупиняє стартування polyfill-а (§2.2).
+5. Інакше повертається об'єкт `{ backend, runStep }`.
+6. Викликаючий код передає `runStep(prompt, { cwd })`:
+   - для SDK — отримує `Promise<{ ok, output }>`, працюючи з обмеженим набором інструментів `Read`/`Edit`/`Bash` та лімітом `maxTurns: 20`;
+   - для CLI — отримує синхронний `{ ok, output }` після завершення дочірнього процесу.
+
+Для тестування потік ін'єктується наскрізно: будь-яку із залежностей (`spawn`, `isInPath`, `canImportSdk`, `query`, `env`, `backend`) можна перевизначити, що дозволяє покривати модуль unit-тестами без реальних процесів і без SDK.
+
+Особливості та інваріанти:
+
+- Пріоритет backend-ів зафіксований у `selectBackend` і не змінюється від виклику до виклику.
+- `runStep` у CLI-варіанті завжди синхронний, у SDK-варіанті — асинхронний; форма результату `{ ok, output }` уніфікована.
+- `output` у CLI завжди склеює `stdout` та `stderr` без розділювача.
+- У SDK-варіанті помилки під час ітерації `query` ловляться й конвертуються в `{ ok: false, output: <message> }`, тобто `runStep` не пробрасує винятки нагору.
+- Значення `null`/`undefined` для `r.status` у `spawnSync`-результатах послідовно нормалізується через `?? 1`, що дає поведінку "невідомий статус == помилка".
+
+## Rebuild Test
+
+Документ описує лише той API, що присутній у файлі `subagent-runner.mjs`:
+
+- Експорти: `isBinaryInPath`, `selectBackend`, `cliRunner`, `sdkRunner`, `createRunner` — усі п'ять перевірено за вихідним кодом.
+- Внутрішня функція `probeSdk` зафіксована як приватна (не експортована).
+- Константа `NO_BACKEND` згадана як модульна.
+- Імпорти `spawnSync` із `node:child_process` та `env` як `processEnv` із `node:process` зафіксовані.
+- Опційна залежність `@anthropic-ai/claude-agent-sdk` згадана з акцентом на динамічний import у двох місцях (`sdkRunner.runStep` та `probeSdk`).
+- Пріоритет `sdk → claude → cursor` і поведінка `createRunner` за відсутності backend (throw `NO_BACKEND`) відповідають коду.
+- Деталі `sdkRunner` (`maxTurns: 20`, `allowedTools: ['Read', 'Edit', 'Bash']`, обробка `msg.type === 'result'` та `msg.is_error`) узяті безпосередньо з тіла функції.
+- Формула `r.status ?? 1` для нормалізації статусу описана точно так, як у коді.
+
+Жодних припущень про невидимі в файлі деталі (тестові файли, інтеграцію з конкретними викликами в інших модулях диспетчера) у документі не зроблено.

package/scripts/dispatcher/lib/executor.mjs

@@ -66,7 +66,12 @@ export async function executePlan(paths, deps) {
       const verdict = await verify(cwd)
       if (verdict.pass) {
         commit(cwd, `flow: step ${step.step} — ${step.task}`) // commit ЛИШЕ після зеленого
-        state = recordTransition(paths, { type: 'step_done', step: step.step }, s => patchStep(s, i, { status: 'done' }), now)
+        state = recordTransition(
+          paths,
+          { type: 'step_done', step: step.step },
+          s => patchStep(s, i, { status: 'done' }),
+          now
+        )
         done = true
       } else {
         state = recordTransition(

package/scripts/dispatcher/lib/flow-resolve.mjs

@@ -90,7 +90,9 @@ export function resolveActiveFlowState({ cwd = processCwd(), branch } = {}, deps
     const label = sanitizeBranch(branch)
     const worktreeDir = worktreePaths(repoRoot, branch).checkout
     if (!exists(worktreeDir)) {
-      return notFound(`worktree для гілки «${branch}» не знайдено (${worktreeDir}) — перевір назву або зроби \`flow init\``)
+      return notFound(
+        `worktree для гілки «${branch}» не знайдено (${worktreeDir}) — перевір назву або зроби \`flow init\``
+      )
     }
     return { statePath: flowStatePath(worktreeDir), worktreeDir, label, autoResolved: false, error: null }
   }

package/scripts/dispatcher/lib/level.mjs

@@ -16,6 +16,30 @@ const L0_WORD_KEYS = ['fix', 'typo', 'bump', 'rename', 'hotfix']
 const L0_SUBSTR_KEYS = ['опечат', 'перейменув']
 /** L2 — багатофайлова фіча/рефактор. */
 const L2_KEYS = ['feature', 'epic', 'refactor', 'рефактор', 'фіча']
+/**
+ * Сигнали складності (cross-cutting rules/checks/correctness): разом із L0-дієсловом
+ * задача НЕ тривіальна. Перекривають L0 (мінімум L2) — щоб rules/checks-роботу не
+ * класифікувати як trivial і не пропускати spec (беклог #2). Підрядком (case-insensitive).
+ */
+const COMPLEXITY_KEYS = [
+  'mdc',
+  'policy',
+  'політик',
+  'rego',
+  'checker',
+  'чекер',
+  'правило',
+  'правила',
+  'rules',
+  'суперечн',
+  'інваріант',
+  'invariant',
+  'порушен',
+  'violation',
+  'кілька файл',
+  'декілька',
+  'meta-'
+]
 
 /**
  * Чи символ — ASCII-літера/цифра (межа слова). `undefined` (край рядка) — не alnum.
@@ -44,7 +68,9 @@ function hasWord(text, word) {
 
 /**
  * Рівень складності задачі за описом: 0 (тривіальне) … 3 (архітектурне).
- * Пріоритет: L3 > L0 > L2 > дефолт L1.
+ * Пріоритет: L3 > L0 (якщо без сигналів складності) > L2/складність > дефолт L1.
+ * Лише сигнал складності перекриває L0-дієслово (`fix mdc checker` → L2, не L0);
+ * L2-ключі порядок L0 не змінюють (`rename feature` лишається L0, як і раніше).
  * @param {string} desc опис задачі
  * @returns {0 | 1 | 2 | 3} рівень
  */
@@ -53,8 +79,8 @@ export function detectLevel(desc) {
   const has = keys => keys.some(k => d.includes(k))
   const isL0 = L0_WORD_KEYS.some(k => hasWord(d, k)) || L0_SUBSTR_KEYS.some(k => d.includes(k))
   if (has(L3_KEYS)) return 3
-  if (isL0) return 0
-  if (has(L2_KEYS)) return 2
+  if (isL0 && !has(COMPLEXITY_KEYS)) return 0
+  if (has(L2_KEYS) || has(COMPLEXITY_KEYS)) return 2
   return 1
 }
 

package/scripts/dispatcher/lib/review.mjs

@@ -43,7 +43,7 @@ export function diffFromBase(base, run, cwd) {
 export function reviewerPrompt(diff, risk) {
   const lens =
     risk === 'high'
-      ? 'ОСОБЛИВА УВАГА БЕЗПЕЦІ: auth/доступи, секрети/токени, ін\'єкції, валідація входу, незворотні операції.'
+      ? "ОСОБЛИВА УВАГА БЕЗПЕЦІ: auth/доступи, секрети/токени, ін'єкції, валідація входу, незворотні операції."
       : ''
   return [
     'Ти — прискіпливий adversarial-рецензент. Знайди баги, ризики й smells, які ВНОСИТЬ або зачіпає цей diff.',

package/scripts/dispatcher/lib/subagent-runner.mjs

@@ -77,7 +77,10 @@ export function sdkRunner(deps = {}) {
       let output = ''
       let ok = true
       try {
-        for await (const msg of query({ prompt, options: { cwd, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] } })) {
+        for await (const msg of query({
+          prompt,
+          options: { cwd, maxTurns: 20, allowedTools: ['Read', 'Edit', 'Bash'] }
+        })) {
           if (typeof msg?.text === 'string') output += msg.text
           if (msg?.type === 'result') ok = msg.is_error !== true
         }
@@ -99,8 +102,7 @@ export async function createRunner(deps = {}) {
   const env = deps.env ?? processEnv
   const isInPath = deps.isInPath ?? (name => isBinaryInPath(name, deps.spawn))
   const canImportSdk = deps.canImportSdk ?? (await probeSdk())
-  const backend =
-    deps.backend ?? selectBackend({ hasApiKey: Boolean(env.ANTHROPIC_API_KEY), canImportSdk, isInPath })
+  const backend = deps.backend ?? selectBackend({ hasApiKey: Boolean(env.ANTHROPIC_API_KEY), canImportSdk, isInPath })
   if (!backend) throw new Error(NO_BACKEND)
   if (backend === 'sdk') return sdkRunner(deps)
   return cliRunner(backend === 'claude' ? 'claude' : 'cursor-agent', deps)