@nitra/cursor 4.1.1 → 5.0.0

package/scripts/dispatcher/lib/docs/planner.md

@@ -1,269 +0,0 @@
-# planner.mjs
-
-## Огляд
-
-Модуль `planner.mjs` — **декларативний планувальник** диспетчера субагентів (відповідає Ф1 зі spec §3). Його завдання — отримати від користувача опис фічі/задачі, сформулювати спеціалізований промпт, передати його зовнішньому субагенту (через ін'єкцію `runner`), а потім **строго валідувати** повернутий JSON-план реалізації та нормалізувати його кроки до уніфікованої структури з полями `step`, `task`, `status`, `retry_count` (плюс опційне `acceptance`).
-
-Поведінка модуля **fail-closed**: будь-яка невідповідність контракту (відсутність JSON-масиву, невалідний JSON, порожній масив, відсутність текстового `task` у кроці, плейсхолдер на кшталт `tbd`/`todo`/`fixme`/`...`/`placeholder`, помилка субагента) призводить до кидання `Error` без часткових результатів. Це гарантує, що подальші стадії (виконання плану) ніколи не отримають частково сформований/невалідований план.
-
-Файл написано як чистий ES-модуль (`.mjs`) без зовнішніх залежностей — лише вбудовані JS-конструкції (`JSON.parse`, `String`, регулярні вирази, `Array.prototype.map`). Це робить його легким для unit-тестування й мокування `runner` у тестах.
-
-## Експорти / API
-
-Модуль експортує **три іменовані функції** (інших експортів немає, default-експорту немає):
-
-| Експорт                               | Тип                                | Призначення                                                                                   |
-| ------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------- |
-| `plannerPrompt(task)`                 | `(string) => string`               | Формує текстовий промпт для субагента-планувальника.                                          |
-| `parsePlan(text)`                     | `(string) => Step[]`               | Парсить і валідує JSON-план із сирого тексту відповіді; повертає нормалізований масив кроків. |
-| `generatePlan({ runner, task, cwd })` | `async ({...}) => Promise<Step[]>` | Високорівнева оркестровка: будує промпт, викликає `runner.runStep`, парсить вихід.            |
-
-Внутрішня (не експортована) константа:
-
-| Ім'я          | Тип      | Значення / опис                                                                                                                           |
-| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `PLACEHOLDER` | `RegExp` | `^(tbd\|todo\|fixme\|\.\.\.\|placeholder)$` із прапором `i` — список «заборонених» текстів кроку, що сигналізують про несформований план. |
-
-### Тип `Step` (нормалізований крок плану)
-
-Об'єкт, який повертають `parsePlan` і `generatePlan` (масивом):
-
-```
-{
-  step: number,            // 0-індексований порядковий номер
-  task: string,            // оригінальний (не тримлений!) текст задачі
-  status: 'pending',       // початковий статус — завжди 'pending'
-  retry_count: 0,          // лічильник повторів — завжди 0
-  acceptance?: string      // опційний критерій приймання (як строка)
-}
-```
-
-## Функції
-
-### `plannerPrompt(task)`
-
-**Сигнатура.** `plannerPrompt(task: string): string`
-
-**Параметри.**
-
-- `task` — текстовий опис фічі/задачі, який отримав диспетчер від виклику верхнього рівня.
-
-**Повертає.** Готовий **system-user** промпт у вигляді одного рядка, склеєного через `\n`. Зміст промпта:
-
-1. Роль: «архітектор», який має розбити задачу.
-2. Обмеження кроку: ≤ 5 хв розробки, чіткі критерії приймання.
-3. Формат відповіді: **ЛИШЕ** JSON-масив без коментарів, кожен елемент — об'єкт `{ "task": "...", "acceptance": "..." }`.
-4. Останній рядок — фактична задача: `Задача: <task>`.
-
-**Side effects.** Немає — функція суто детермінована й pure. Її вихід можна логувати, кешувати, передавати в тести як snapshot.
-
-**Особливості.**
-
-- Не екранує і не санітизує `task` — викликач відповідає за те, що рядок не зламає форматування промпта (хоча для рядкового рендеру це й не критично).
-- Не вставляє приклади чи додаткові few-shot блоки — мінімалістичний контракт.
-
-### `parsePlan(text)`
-
-**Сигнатура.** `parsePlan(text: string): Step[]`
-
-**Параметри.**
-
-- `text` — сира відповідь субагента; може містити markdown-огорожі (наприклад, ` ```json ... ``` `), пояснювальний текст до/після масиву тощо.
-
-**Повертає.** Масив нормалізованих кроків (див. тип `Step` вище).
-
-**Алгоритм.**
-
-1. Конвертує вхід у рядок через `String(text)` — захист від `null`/`undefined`/буферів.
-2. Шукає **перший `[`** через `indexOf('[')` і **останній `]`** через `lastIndexOf(']')`. Це робить парсер толерантним до markdown-огорож, преамбули чи коментарів навколо JSON-масиву.
-3. Якщо хоча б одна з дужок не знайдена або порядок інвертовано (`end < start`) — кидає `Error('planner: не знайдено JSON-масив плану — fail-closed')`.
-4. Виокремлює зріз `str.slice(start, end + 1)` і парсить через `JSON.parse`. На SyntaxError кидає `Error('planner: невалідний JSON плану — fail-closed')`.
-5. Перевіряє, що результат — **непорожній масив**; інакше — `Error('planner: план має бути непорожнім масивом — fail-closed')`.
-6. Мапить кожен елемент:
-   - Витягує `task`: якщо елемент сам є рядком — то він і є task; інакше `s?.task`.
-   - Якщо `task` відсутній або не рядок — кидає `Error('planner: крок <i> без текстового поля task — fail-closed')`.
-   - Тримить копію (`task.trim()`) і перевіряє: непорожній і **не** збігається з `PLACEHOLDER`. Інакше — `Error('planner: крок <i> — placeholder/порожній task (<task>) — fail-closed')`.
-   - Формує об'єкт `{ step: i, task, status: 'pending', retry_count: 0 }`. Важливо: у поле `task` зберігається **оригінальний** (нетримлений) рядок, валідується лише тримлений варіант.
-   - Якщо в сирому елементі є поле `acceptance` (truthy) — додає `step.acceptance = String(s.acceptance)`.
-
-**Повертає.** Масив об'єктів `Step` у тому ж порядку, що й у вхідному масиві; індекс `step` — 0-індексований, відповідає позиції в масиві.
-
-**Side effects.** Немає — pure-функція. Винятки кидаються синхронно; внутрішнього логування, мутацій глобального стану чи I/O немає.
-
-**Покриті граничні випадки.**
-
-- Markdown-огорожі / преамбула / postамбула навколо JSON.
-- Елемент-рядок (`"крок 1"`) замість `{ task: "крок 1" }`.
-- Цифрові `task` (`123`), `null`, відсутні — все відсіюється.
-- Регістронезалежні плейсхолдери (`TBD`, `Todo`, `FIXME`, `...`, `Placeholder`).
-- Порожній масив `[]` — відхиляється.
-- Будь-який `task` із пробілами навколо плейсхолдера (наприклад, `"  tbd  "`) також відсіюється завдяки `.trim()` перед регуляркою.
-
-### `generatePlan({ runner, task, cwd })`
-
-**Сигнатура.**
-
-```
-async generatePlan(input: {
-  runner: { runStep: (prompt: string, opts?: { cwd?: string })
-             => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> },
-  task: string,
-  cwd?: string
-}): Promise<Step[]>
-```
-
-**Параметри (деструктуровані).**
-
-- `runner` — обов'язкова ін'єкція «бігуна» субагента. Очікується об'єкт із методом `runStep(prompt, opts?)`, що повертає (або резолвить у Promise) `{ ok: boolean, output: string }`. Контракт навмисно мінімальний — це спрощує мокування в тестах.
-- `task` — текстовий опис фічі/задачі; передається у `plannerPrompt`.
-- `cwd` — опційний робочий каталог, який пробрасується у `runner.runStep` через `{ cwd }`.
-
-**Повертає.** `Promise<Step[]>` — нормалізований план від `parsePlan`.
-
-**Алгоритм.**
-
-1. Формує промпт через `plannerPrompt(task)`.
-2. Викликає `await runner.runStep(prompt, { cwd })` — підтримує і синхронний, і асинхронний `runStep` (await на не-promise — no-op).
-3. Якщо `res.ok === false` — кидає `Error('planner: субагент-планувальник завершився помилкою[:\n<output>]')`. Якщо `res.output` truthy — він приєднується до повідомлення з префіксом `:\n` для зручної діагностики.
-4. Передає `res.output` у `parsePlan` і повертає його результат (валідні винятки парсера пробулькують далі).
-
-**Side effects.**
-
-- Викликає `runner.runStep`, який у реальному середовищі стартує субагента (запис файлів, мережа, процеси — все на боці `runner`). Сам модуль `planner.mjs` ніяких I/O не виконує.
-- Може кидати `Error` як від власних перевірок, так і від `parsePlan`.
-
-**Обробка помилок.** Будь-яка помилка веде до **повного провалу** (без часткового плану) — fail-closed контракт, на який спираються наступні Ф2/Ф3 диспетчера.
-
-## Залежності
-
-**Зовнішні npm-залежності:** немає.
-
-**Імпорти у файлі:** немає (`import`-ів нема — модуль самодостатній).
-
-**Що використовується (вбудоване в JS-runtime):**
-
-- `String(...)` — нормалізація вхідного значення в `parsePlan`.
-- `JSON.parse` — парсинг витягнутого JSON-зрізу.
-- `Array.isArray`, `Array.prototype.map` — перевірка типу й мапінг.
-- `RegExp` (`/^(tbd|todo|fixme|\.\.\.|placeholder)$/i`) — детектор плейсхолдерів.
-- `String.prototype.indexOf`/`lastIndexOf`/`slice`/`trim`.
-
-**Ін'єкції (контракт ззовні):**
-
-- `runner` із методом `runStep(prompt, opts?)` — інверсія залежностей; реалізація лежить за межами цього модуля (зазвичай — окремий модуль `dispatcher/lib/runner*.mjs`).
-
-**Хто залежить від модуля (типові споживачі).**
-
-- Оркестратор/диспетчер субагентів верхнього рівня — імпортує `generatePlan` для побудови плану перед виконанням.
-- Юніт-тести — як правило, ймовірно імпортують `parsePlan` і `plannerPrompt` прямо для перевірки контракту без `runner`.
-
-Точні шляхи споживачів у цьому документі **не фіксуються** (модуль документується ізольовано).
-
-## Потік виконання / Використання
-
-### Типовий happy-path (з боку диспетчера)
-
-1. Диспетчер отримує `task` (опис фічі) і має `runner`-реалізацію.
-2. Викликає `await generatePlan({ runner, task, cwd })`.
-3. `generatePlan` будує промпт через `plannerPrompt(task)`.
-4. `runner.runStep(prompt, { cwd })` стартує субагента-«архітектора», який повертає `{ ok: true, output: '[ ... JSON ... ]' }` (можливо з markdown-огорожею).
-5. `parsePlan(output)` витягує JSON-зріз від `[` до `]`, парсить, валідує, нормалізує — повертає масив `Step`.
-6. Диспетчер отримує `Step[]` і передає його наступній фазі (Ф2 — виконання кроків).
-
-### Sad-path сценарії (fail-closed)
-
-| Сценарій                                                     | Точка падіння  | Текст помилки (рівно)                                                  |
-| ------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------- |
-| `runner.runStep` повернув `{ ok: false, output: '' }`        | `generatePlan` | `planner: субагент-планувальник завершився помилкою`                   |
-| `runner.runStep` повернув `{ ok: false, output: '<lorem>' }` | `generatePlan` | `planner: субагент-планувальник завершився помилкою:\n<lorem>`         |
-| У відповіді немає `[` або `]` (або в зворотному порядку)     | `parsePlan`    | `planner: не знайдено JSON-масив плану — fail-closed`                  |
-| JSON всередині `[...]` неваліден                             | `parsePlan`    | `planner: невалідний JSON плану — fail-closed`                         |
-| Результат — не масив або порожній                            | `parsePlan`    | `planner: план має бути непорожнім масивом — fail-closed`              |
-| Крок без `task` (або не-рядок)                               | `parsePlan`    | `planner: крок <i> без текстового поля task — fail-closed`             |
-| Крок з порожнім/плейсхолдер-`task`                           | `parsePlan`    | `planner: крок <i> — placeholder/порожній task (<task>) — fail-closed` |
-
-### Приклади використання
-
-**Лише парсинг (наприклад, у тесті):**
-
-````
-import { parsePlan } from './planner.mjs'
-
-const text = '```json\n[\n  { "task": "init repo", "acceptance": "git init ok" },\n  "lint config"\n]\n```'
-const steps = parsePlan(text)
-// steps[0] === { step: 0, task: 'init repo', status: 'pending', retry_count: 0, acceptance: 'git init ok' }
-// steps[1] === { step: 1, task: 'lint config', status: 'pending', retry_count: 0 }
-````
-
-**Повна оркестровка з мок-runner:**
-
-```
-import { generatePlan } from './planner.mjs'
-
-const runner = {
-  runStep: async (prompt) => ({
-    ok: true,
-    output: '[{ "task": "крок 1" }, { "task": "крок 2", "acceptance": "тести зелені" }]'
-  })
-}
-
-const plan = await generatePlan({ runner, task: 'додати feature X', cwd: process.cwd() })
-// plan.length === 2; plan[1].acceptance === 'тести зелені'
-```
-
-**Реакція на fail-closed:**
-
-```
-try {
-  await generatePlan({ runner, task: '...' })
-} catch (e) {
-  // e.message починається з 'planner: ' — далі диспетчер може віддати помилку нагору
-}
-```
-
-### Інваріанти, на які можна спиратися
-
-- Поверне рівно стільки кроків, скільки було у вхідному JSON-масиві (mapping 1:1, порядок збережено).
-- `step` зростає монотонно від `0` до `arr.length - 1`.
-- `status === 'pending'`, `retry_count === 0` — для **кожного** свіжого кроку (новостворений план — завжди «незачеплений»).
-- Поле `acceptance` присутнє **лише** якщо в сирому елементі воно truthy; інакше відсутнє (не `undefined`, а немає ключа взагалі).
-- Поле `task` зберігається **в оригінальному вигляді** (з пробілами по краях), валідація використовує тримлений варіант — тобто можливі «візуально нетримлені» рядки в результаті, але вони гарантовано не плейсхолдери й не порожні.
-
-## Rebuild Test
-
-Цей розділ описує контракт настільки повно, що його можна використати як специфікацію для повторної реалізації файлу з нуля.
-
-**Реалізаційні вимоги:**
-
-1. ES-модуль `.mjs` без імпортів.
-2. Внутрішня константа-регулярка `PLACEHOLDER = /^(tbd|todo|fixme|\.\.\.|placeholder)$/i`.
-3. Експортувати рівно три функції: `plannerPrompt`, `parsePlan`, `generatePlan` (іменовані експорти, без default).
-4. `plannerPrompt(task)` повертає рядок, склеєний через `\n` з 5 рядків (4 інструктивних + порожній + `Задача: <task>`).
-5. `parsePlan(text)`:
-   - Конвертувати в рядок через `String(text)`.
-   - Знайти `start = indexOf('[')`, `end = lastIndexOf(']')`. Якщо `start === -1 || end === -1 || end < start` — кинути `'planner: не знайдено JSON-масив плану — fail-closed'`.
-   - Спробувати `JSON.parse(slice(start, end+1))`; на catch — кинути `'planner: невалідний JSON плану — fail-closed'`.
-   - Якщо результат не масив або порожній — кинути `'planner: план має бути непорожнім масивом — fail-closed'`.
-   - Для кожного `(s, i)`: визначити `task = typeof s === 'string' ? s : s?.task`; якщо falsy або не string — кинути `'planner: крок <i> без текстового поля task — fail-closed'`; перевірити `trimmed = task.trim()` — якщо falsy або матчить `PLACEHOLDER` — кинути `'planner: крок <i> — placeholder/порожній task (<task>) — fail-closed'`.
-   - Сформувати `{ step: i, task, status: 'pending', retry_count: 0 }`; якщо `s?.acceptance` — додати `acceptance: String(s.acceptance)`.
-6. `generatePlan({ runner, task, cwd })` — `async`:
-   - `const res = await runner.runStep(plannerPrompt(task), { cwd })`.
-   - Якщо `!res.ok` — кинути `'planner: субагент-планувальник завершився помилкою'` плюс `':\n' + res.output` якщо `res.output` truthy.
-   - Інакше `return parsePlan(res.output)`.
-
-**Контрольні приклади (повинні проходити після rebuild):**
-
-| Вхід `parsePlan`                                   | Очікуваний результат                                                       |
-| -------------------------------------------------- | -------------------------------------------------------------------------- |
-| `'[{"task":"a"}]'`                                 | `[{ step:0, task:'a', status:'pending', retry_count:0 }]`                  |
-| `'prefix [{"task":"a","acceptance":"ok"}] suffix'` | `[{ step:0, task:'a', status:'pending', retry_count:0, acceptance:'ok' }]` |
-| `'[\"a\",\"b\"]'`                                  | `[{step:0,task:'a',...},{step:1,task:'b',...}]`                            |
-| `'[]'`                                             | throw `'planner: план має бути непорожнім масивом — fail-closed'`          |
-| `'no json here'`                                   | throw `'planner: не знайдено JSON-масив плану — fail-closed'`              |
-| `'[{"task":"tbd"}]'`                               | throw `'planner: крок 0 — placeholder/порожній task (tbd) — fail-closed'`  |
-| `'[{"task":""}]'`                                  | throw `'planner: крок 0 — placeholder/порожній task () — fail-closed'`     |
-| `'[{"task":123}]'`                                 | throw `'planner: крок 0 без текстового поля task — fail-closed'`           |
-| `'[oops'` (нема `]`)                               | throw `'planner: не знайдено JSON-масив плану — fail-closed'`              |
-| `'[invalid json]'`                                 | throw `'planner: невалідний JSON плану — fail-closed'`                     |
-
-Якщо реалізація проходить усі ці кейси й тримає сигнатури/тексти помилок з таблиць — її можна вважати функціонально еквівалентною оригінальному `planner.mjs`.

package/scripts/dispatcher/lib/docs/review.md

@@ -1,255 +0,0 @@
-# review.mjs
-
-## Огляд
-
-Модуль реалізує команду `flow review` — adversarial-перевірку коду **після** його написання (концепція з BMAD quick-dev: спершу self-check, потім adversarial-review). Незалежний субагент-рецензент читає **лише** `git diff` від базового комміту й шукає логічні баги, ризики та smells, які не ловлять механічні гейти (lint + coverage) у команді `verify`.
-
-Команда є **інформативною**: ворота м'які, тож exit code завжди `0`, якщо вдалося запустити рецензію. Код `1` повертається лише за технічної неможливості (немає стану flow, не вдалось створити runner). Кількість рецензентів визначається полем `level` стану flow (через `reviewersFor`), а додаткова security-лінза вмикається для `risk === 'high'`.
-
-Усі сторонні залежності (запуск процесів, runner субагента, годинник) **ін'єктуються** через об'єкт `deps`, тож модуль повністю тестується без реального git та LLM.
-
-Результати рецензії (`{ at, reviewers, findings }`) фіксуються в `.flow.json` через `recordTransition` і виводяться у лог зі зрозумілими емодзі-іконками за severity.
-
-## Експорти / API
-
-Модуль експортує чотири іменовані функції:
-
-| Експорт                        | Тип              | Призначення                                                                          |
-| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------ |
-| `diffFromBase(base, run, cwd)` | `function`       | Будує текст diff: закомічене `base...HEAD` + working tree `git diff`.                |
-| `reviewerPrompt(diff, risk)`   | `function`       | Формує промпт для adversarial-рецензента з фокусом на diff (опційно security-лінза). |
-| `parseFindings(text)`          | `function`       | Витягає JSON-масив findings з відповіді субагента (fail-soft).                       |
-| `dedupeFindings(findings)`     | `function`       | Дедуплікує findings за ключем `(file, issue)`.                                       |
-| `review(_rest, deps)`          | `async function` | Головна точка входу команди `flow review`.                                           |
-
-Внутрішня (не експортується) функція `severityIcon(severity)` повертає емодзі-маркер.
-
-Константа модульного scope:
-
-- `DIFF_LIMIT = 12_000` — максимальна кількість символів diff, що потрапляє у промпт рецензента (захист від роздування контексту).
-
-## Функції
-
-### `diffFromBase(base, run, cwd)`
-
-**Сигнатура:** `(base: string, run: (cmd, args, opts) => { stdout: string }, cwd: string) => string`
-
-**Параметри:**
-
-- `base` — базовий комміт, від якого рахується diff (наприклад, `HEAD~1` або значення з `state.metadata.base_commit`).
-- `run` — ін'єктований git-раннер. Виклик `run('git', args, { cwd })` має повертати об'єкт із полем `stdout`.
-- `cwd` — шлях до worktree, у якому виконуються git-команди.
-
-**Повертає:** склеєний рядок з двох частин — `git diff base...HEAD` (закомічене) і `git diff` (робоче дерево), розділених `\n`, з обрізаними пробілами по краях.
-
-**Side effects:** виконує два процеси `git` через ін'єктований `run`. Без `run` — чиста функція.
-
-**Особливості:** `stdout` нормалізується через `?? ''`, тому якщо одна з команд не повернула вивід, інша частина не "забивається" `undefined`.
-
----
-
-### `reviewerPrompt(diff, risk)`
-
-**Сигнатура:** `(diff: string, risk?: string) => string`
-
-**Параметри:**
-
-- `diff` — текст diff для рецензування (обрізається до `DIFF_LIMIT` символів).
-- `risk` — рівень ризику flow: `'low'`, `'med'`, `'high'`. За `risk === 'high'` додається security-лінза з акцентом на auth/секрети/ін'єкції/незворотні операції.
-
-**Повертає:** готовий текст промпта для adversarial-рецензента — рядки, склеєні через `\n` (порожні через `lens` або інші falsy-вставки відфільтровуються `.filter(Boolean)`).
-
-**Side effects:** немає (чиста функція).
-
-**Ключові вимоги в промпті:**
-
-1. Рецензент шукає баги/ризики/smells, які **вносить або зачіпає** саме цей diff.
-2. Якщо доступний інструмент `Read` — точково читає referenced-файли для верифікації cross-file тверджень; інакше працює лише з diff.
-3. Сусідні файли — для контексту, **не** для пошуку преіснуючих багів.
-4. Заборонено нефальсифіковні findings виду "з diff не видно / можливо" — або підтвердити читанням, або відкинути.
-5. Формат відповіді — **лише** JSON-масив `[{ severity, file, issue, suggestion }]`; якщо проблем нема — `[]`.
-
----
-
-### `parseFindings(text)`
-
-**Сигнатура:** `(text: string) => Array<{ severity?: string, file?: string, issue?: string, suggestion?: string }>`
-
-**Параметри:**
-
-- `text` — сирий вивід субагента-рецензента.
-
-**Повертає:** масив findings. Якщо JSON-масив не знайдено або парсинг впав — повертає `[]`.
-
-**Алгоритм:**
-
-1. Знаходить індекси першого `[` та останнього `]` у тексті.
-2. Якщо хоча б одного нема, або `end < start` — повертає `[]`.
-3. Парсить підрядок `[...]` через `JSON.parse`.
-4. Якщо результат — масив, повертає його; інакше або при exception — `[]`.
-
-**Side effects:** немає. Fail-soft: будь-яке сміття/невалідний JSON безпечно перетворюється на порожній масив.
-
----
-
-### `dedupeFindings(findings)`
-
-**Сигнатура:** `(findings: object[]) => object[]`
-
-**Параметри:**
-
-- `findings` — масив findings (можливо з дублікатами).
-
-**Повертає:** новий масив без дублікатів за ключем `${file}::${issue}`, зі збереженням порядку першого входження.
-
-**Side effects:** немає (чиста функція, але створює новий масив).
-
-**Особливості:** `f?.file ?? ''` і `f?.issue ?? ''` — `undefined`/`null` нормалізуються до пустого рядка, тож два findings без обох полів вважаються дублікатами.
-
----
-
-### `severityIcon(severity)` _(internal)_
-
-**Сигнатура:** `(severity: string) => string`
-
-**Параметри:**
-
-- `severity` — рівень: `'high'` | `'med'` | будь-що інше.
-
-**Повертає:** емодзі-іконку:
-
-- `'high'` → червоне коло;
-- `'med'` → жовте коло;
-- решта (включно з `'low'`, `undefined`) → біле коло.
-
-**Side effects:** немає.
-
----
-
-### `review(_rest, deps)`
-
-**Сигнатура:** `(_rest: string[], deps?: object) => Promise<number>`
-
-**Параметри:**
-
-- `_rest` — позиційні аргументи CLI (не використовуються; передається для уніфікованої сигнатури команд диспатчера).
-- `deps` — об'єкт ін'єкцій:
-  - `cwd` — стартова робоча тека (за замовчуванням `process.cwd()`);
-  - `branch` — гілка для авторезолву flow-стану (необов'язково);
-  - `log` — функція логування (за замовчуванням `console.error`);
-  - `run` — git-раннер (за замовчуванням `realRun` з `./commands.mjs`);
-  - `runner` — готовий runner субагента; якщо не передано — створюється через `createRunner(deps)`;
-  - `now` — джерело часу (за замовчуванням `Date.now`).
-
-**Повертає:** `Promise<number>` — exit code:
-
-- `0` — нормальне завершення (включно з випадком "нема змін" та з будь-якою кількістю findings);
-- `1` — технічна неможливість виконати рецензію (нема активного flow-стану, нема `.flow.json`, не вдалось створити runner).
-
-**Side effects:**
-
-- Викликає `resolveActiveFlowState` для пошуку активного flow.
-- Читає файл стану через `readState(statePath)`.
-- Виконує git через `run` (всередині `diffFromBase`).
-- Створює runner субагента (`createRunner`) і запускає `runner.runStep(prompt, { cwd })` стільки разів, скільки повернув `reviewersFor`.
-- Записує транзицію в state-store через `recordTransition`, додаючи поле `review: { at, reviewers, findings }`.
-- Логує кожен finding з емодзі за severity та підсумок `review: N findings (рецензентів: M)`. Якщо є high-severity — додатковий warning.
-
-**Покроковий потік:**
-
-1. Зчитує `cwd0`, `log`, `run`, `now` з `deps` із дефолтами.
-2. Резолвить активний flow-стан через `resolveActiveFlowState({ cwd: cwd0, branch }, deps)`.
-   - Якщо `statePath` пустий — лог помилки + `return 1`.
-   - Якщо `autoResolved` — інформативний лог.
-3. Робочий `cwd` = `resolved.worktreeDir ?? cwd0`.
-4. Читає стан `state = readState(statePath)`. Якщо немає — лог `review: стану нема — спершу 'flow init'` + `return 1`.
-5. Бере `base = state.metadata?.base_commit ?? 'HEAD~1'`.
-6. Будує `diff = diffFromBase(base, run, cwd)`. Якщо пустий — лог `review: нема змін від base — нічого ревʼювити` + `return 0`.
-7. Готує `runner`: бере з `deps.runner`, інакше пробує `await createRunner(deps)`. На exception — лог `review: ${error.message}` + `return 1`.
-8. Обчислює `reviewers = reviewersFor(state.level ?? 1, state.risk)` — скільки паралельних рецензентів запустити.
-9. Будує промпт `reviewerPrompt(diff, state.risk)`.
-10. Запускає `reviewers` копій рецензента паралельно через `Promise.all` + `runner.runStep(prompt, { cwd })`.
-11. Збирає findings: для кожного результату з `r.ok === true` парсить через `parseFindings(r.output)`, потім `flatMap` + `dedupeFindings`.
-12. Викликає `recordTransition` з `type: 'review'`, кількістю findings, reducer-функцією, що додає поле `review`, і `now`.
-13. Логує кожен finding: `${іконка} ${file ?? '?'}: ${issue ?? ''}`.
-14. Якщо є high-severity findings — додатковий warning рядок.
-15. Підсумковий лог `review: N findings (рецензентів: M)` і `return 0`.
-
-## Залежності
-
-### Зовнішні (Node.js standard)
-
-- `cwd as processCwd` з `node:process` — дефолтний CWD для команди.
-
-### Внутрішні модулі
-
-- `./commands.mjs` — `realRun`: дефолтний раннер shell-команд (`git`).
-- `./events.mjs` — `flowEventsPath`: шлях до файла подій flow для `recordTransition`.
-- `./level.mjs` — `reviewersFor(level, risk)`: скільки adversarial-рецензентів запускати на даному рівні строгості та ризику.
-- `./state-store.mjs`:
-  - `readState(statePath)` — читає `.flow.json`;
-  - `recordTransition(paths, event, reducer, now)` — атомарно оновлює стан і дописує подію в events-лог.
-- `./flow-resolve.mjs` — `resolveActiveFlowState({ cwd, branch }, deps)`: знаходить активний flow за CWD або з авторезолвом по гілці; повертає `{ statePath, worktreeDir, label, autoResolved, error }`.
-- `./subagent-runner.mjs` — `createRunner(deps)`: фабрика об'єкта з методом `runStep(prompt, opts) → Promise<{ ok, output }>` для запуску LLM-субагента.
-
-### Зовнішні fail-points
-
-- `git` (через `run`).
-- Запуск LLM-субагента (через `runner.runStep`), що, ймовірно, використовує Claude CLI або аналог.
-
-## Потік виконання / Використання
-
-### Типове використання як CLI-команди
-
-Команда `review` зареєстрована у dispatcher і викликається так:
-
-```bash
-flow review
-```
-
-Алгоритм:
-
-1. Користувач має активний flow (створений через `flow init`) з `.flow.json` у поточному worktree або резолвиться авто.
-2. У стані лежить `metadata.base_commit` (комміт-стартер flow).
-3. Команда збирає diff від `base_commit` до HEAD + working tree, формує промпт і запускає рецензентів.
-4. Findings виводяться в stderr і зберігаються в `.flow.json` під ключем `review`.
-
-### Програмне використання (тести)
-
-```javascript
-import { review, diffFromBase, reviewerPrompt, parseFindings, dedupeFindings } from './review.mjs'
-
-// Тест без git та LLM
-const fakeRun = (cmd, args) => ({ stdout: 'diff text' })
-const fakeRunner = {
-  async runStep(prompt, { cwd }) {
-    return { ok: true, output: '[{"severity":"high","file":"a.js","issue":"npe","suggestion":"check null"}]' }
-  }
-}
-const exit = await review([], {
-  cwd: '/tmp/repo',
-  run: fakeRun,
-  runner: fakeRunner,
-  now: () => 0,
-  log: () => {}
-})
-// exit === 0
-```
-
-### Інваріанти та контракти
-
-1. **Exit-code контракт:** `0` за успішного запуску рецензії (включно з нульовою кількістю findings); `1` лише за відсутності стану або runner-а.
-2. **Ідемпотентність:** повторний запуск `review` перезаписує поле `review` у стані поточним підсумком; події накопичуються в events-лозі.
-3. **Fail-soft парсинг:** будь-яке "сміття" від рецензента → пустий список findings, а не exception.
-4. **Дедуплікація** — по `(file, issue)`, **не** по `suggestion`/`severity`. Різні рецензенти, що знайшли одну проблему по-різному, схлопуються в один finding.
-5. **Контекст-ліміт:** diff обрізається до 12 000 символів — рецензент бачить лише початок великих diff'ів.
-
-### Rebuild Test
-
-Якщо файл видалити й переписати на основі цієї документації, відновлення має містити:
-
-1. Імпорти: `cwd as processCwd` з `node:process`; `realRun` з `./commands.mjs`; `flowEventsPath` з `./events.mjs`; `reviewersFor` з `./level.mjs`; `readState`, `recordTransition` з `./state-store.mjs`; `resolveActiveFlowState` з `./flow-resolve.mjs`; `createRunner` з `./subagent-runner.mjs`.
-2. Константу `DIFF_LIMIT = 12_000`.
-3. Експорти `diffFromBase`, `reviewerPrompt`, `parseFindings`, `dedupeFindings`, `review` із сигнатурами та поведінкою, описаними вище.
-4. Внутрішню `severityIcon` із трьома кейсами (`high` → червоний, `med` → жовтий, інше → білий).
-5. У `review`: всі гілки `return 1` (нема `statePath`, нема стану, помилка `createRunner`); `return 0` за пустого diff; запуск `reviewers` копій рецензента через `Promise.all`; фільтрацію `r.ok` перед `parseFindings`; `dedupeFindings` після `flatMap`; виклик `recordTransition` з полем `review: { at, reviewers, findings }`; логування з іконками + warning для high-severity + підсумок.