@nitra/cursor 3.21.1 → 3.23.0

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

@@ -0,0 +1,255 @@
+# 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 + підсумок.

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

@@ -0,0 +1,240 @@
+# reviewer.mjs
+
+## Огляд
+
+Модуль `reviewer.mjs` реалізує **Level-1 «Суддю»** з §8.4 специфікації Dispatcher-а: чистий, детермінований раннер **Quality Gates** (§5), що повертає структурований verdict про якість поточного робочого дерева.
+
+Призначення:
+
+- Запустити послідовність gate-перевірок (за замовчуванням — `lint` і `coverage --changed`) через **ін'єктований** runner-процесів.
+- Зупинитись на першому проваленому gate (`fail-fast`) і повернути захоплений `stdout/stderr`.
+- За умови **повного** проходження зняти `worktree-fingerprint` (відбиток дерева), щоб пізніше можна було відрізнити «свіжий» verdict від «протухлого» (stale): якщо файли змінилися після зняття fingerprint-а — попередній verdict більше нерелевантний.
+
+Архітектурні принципи:
+
+- Модуль **не знає** про LLM, API-ключі, мережу чи Anthropic SDK. Це **чистий FS/Git/процеси**-рівень.
+- Всі побічні ефекти (виклик дочірніх процесів, обчислення fingerprint-а) **ін'єктуються через параметри** — це робить функцію тестопридатною без `child_process`-моків і без реальних запусків ESLint/Vitest/Stryker.
+- Один і той самий `runReview` обслуговує два сценарії:
+  1. **Пасивний Турнікет** — команда `flow verify` (фінальна перевірка перед merge/commit).
+  2. **Активний Раннер** — per-step Ф4 (фаза 4 з flow-циклу, що оцінює крок ітерації).
+- Gate-и за замовчуванням **scoped до змінених файлів**: `lint` — quick-режим через `changed-files.mjs`; `coverage --changed` — vitest `--changed` плюс Stryker `--mutate` по diff від base-гілки. Турнікет та per-step перевіряють лише змінене; повний прогін coverage — окрема операція (`bun run coverage`, скіл `/n-coverage-fix`).
+
+## Експорти / API
+
+Модуль експортує дві сутності:
+
+| Експорт         | Тип                                                     | Призначення                                                                |
+| --------------- | ------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `DEFAULT_GATES` | `Array<{ name: string, cmd: string[] }>` (named export) | Канонічний список gate-ів за замовчуванням: `lint` і `coverage --changed`. |
+| `runReview`     | `function` (named export)                               | Виконує послідовність gate-ів і повертає `verdict`-об'єкт.                 |
+
+Імпорт:
+
+```js
+import { runReview, DEFAULT_GATES } from './reviewer.mjs'
+```
+
+### `DEFAULT_GATES`
+
+Сталий масив із двома gate-ами, у фіксованому порядку:
+
+```js
+export const DEFAULT_GATES = [
+  { name: 'lint', cmd: ['npx', '@nitra/cursor', 'lint'] },
+  { name: 'coverage', cmd: ['npx', '@nitra/cursor', 'coverage', '--changed'] }
+]
+```
+
+Семантика полів:
+
+- `name` — людиночитна назва gate-у; повертається у `verdict.gates[i].name`.
+- `cmd` — масив `[executable, ...args]`. Перший елемент передається в `run` як виконуваний файл, решта — як аргументи.
+
+Послідовність визначає **порядок** виконання та fail-fast-поведінку: `lint` запускається першим, бо він дешевший і ловить більшість регресій; `coverage` — другим, бо триваліший (включає тести + мутаційне тестування Stryker).
+
+## Функції
+
+### `runReview({ run, cwd, gates, fingerprint })`
+
+Проганяє gate-и послідовно, повертає structured verdict.
+
+**Сигнатура:**
+
+```ts
+runReview(input: {
+  run: (cmd: string, args: string[], opts: { cwd: string })
+       => { status: number, stdout?: string, stderr?: string },
+  cwd: string,
+  gates?: Array<{ name: string, cmd: string[] }>,
+  fingerprint?: () => string | null
+}): {
+  pass: boolean,
+  gates: Array<{ name: string, ok: boolean }>,
+  failedOutput: string | null,
+  fingerprint: string | null
+}
+```
+
+**Параметри (всі — поля об'єктного аргументу):**
+
+- `run` — **обов'язковий**. Синхронна (або синхронно-сумісна за shape) функція запуску дочірнього процесу. Має сигнатуру `(cmd, args, opts)` й мусить повертати об'єкт із принаймні `status: number`; опційно `stdout: string` і `stderr: string`. Передбачається, що це обгортка над `Bun.spawnSync` / `node:child_process.spawnSync`, але реалізація лишається за викликачем. Це **ін'єкція** — модуль сам процесів не породжує.
+- `cwd` — **обов'язковий**. Робоча директорія, в якій виконувати кожен gate. Передається у виклик `run(..., { cwd })`. Має бути коренем worktree, з якого gate-команди (`npx @nitra/cursor lint` тощо) бачать правильну монорепу.
+- `gates` — опційний. Перевизначає список gate-ів. За замовчуванням — `DEFAULT_GATES`. Дозволяє тестам/скриптам прогнати кастомний набір (наприклад, лише `lint`, або додати власний gate `typecheck`).
+- `fingerprint` — опційний. Функція без аргументів, що повертає `string | null` — відбиток поточного стану worktree. За замовчуванням — `() => worktreeFingerprint()` (див. `../../utils/worktree-fingerprint.mjs`). Викликається **лише** у випадку повного pass.
+
+**Повертає** verdict-об'єкт:
+
+- `pass: boolean` — `true` лише якщо **всі** gate-и завершились зі статусом `0`. Якщо `gates` порожній (`[]`), результат `pass: true` (вакуумна істина: `results.length === gates.length === 0` і `every` на порожньому масиві — `true`).
+- `gates: Array<{ name, ok }>` — звіт за кожним фактично виконаним gate-ом. У разі fail-fast масив містить **усі попередні** `{ ok: true }` плюс **один** `{ ok: false }`; gate-и після провалу до масиву **не потрапляють**.
+- `failedOutput: string | null` — конкатенація `stdout` і `stderr` першого проваленого gate-у, обрізана `trim()`-ом. Якщо обидва стріми порожні після trim — `null`. У разі pass — `null`.
+- `fingerprint: string | null` — результат `fingerprint()`, **тільки** якщо `pass === true`; інакше `null`. Це навмисно: stale-перевірка має сенс лише для свіжого позитивного verdict-у.
+
+**Семантика `ok`:**
+
+```js
+const ok = (r?.status ?? 1) === 0
+```
+
+- `r === undefined`/`null` або `r.status === undefined` → трактується як **fail** (`status` defaultиться у `1`).
+- `r.status === 0` → **ok**.
+- Будь-який інший числовий код → **fail**.
+
+**Логіка fail-fast:**
+
+```js
+for (const g of gates) {
+  const r = run(g.cmd[0], g.cmd.slice(1), { cwd })
+  const ok = (r?.status ?? 1) === 0
+  results.push({ name: g.name, ok })
+  if (!ok) {
+    failedOutput = `${r?.stdout ?? ''}\n${r?.stderr ?? ''}`.trim() || null
+    break
+  }
+}
+```
+
+- Розбиття `cmd` на `[head, ...rest]` через `g.cmd[0]` і `g.cmd.slice(1)`.
+- Якщо `stdout`/`stderr` відсутні — підставляється `''`, склейка через `\n`, далі `trim()`. Якщо після trim рядок порожній — повертається `null`, а не `""` (короткозамкнення `|| null`).
+
+**Логіка fingerprint:**
+
+```js
+const pass = results.length === gates.length && results.every(x => x.ok)
+return { pass, gates: results, failedOutput, fingerprint: pass ? fingerprint() : null }
+```
+
+- `pass` істинний лише якщо **жодного break-у** не сталось (довжини масивів збігаються) **і** всі результати `ok`.
+- Виклик `fingerprint()` — **ліниво**, лише на pass-гілці; на fail зайвої роботи не робимо.
+
+**Side effects:**
+
+Сам `runReview` побічних ефектів **не має**: ані до файлової системи, ані до мережі, ані до stdout/stderr процесу-хоста. Усі побічні ефекти інкапсульовано в **ін'єкціях** `run` (запуск процесу, читання вихідних потоків) і `fingerprint` (за замовчуванням — обхід worktree для побудови відбитка). Це робить функцію **детермінованою при фіксованих ін'єкціях** і повністю unit-тестопридатною без stubs на `child_process`/`fs`.
+
+**Особливості й edge-cases:**
+
+- **Порожній `gates`**: `pass === true`, `gates: []`, `failedOutput: null`, `fingerprint: fingerprint()`. У такому разі fingerprint **усе одно** буде знятий — повний pass із 0 перевірок формально успіх.
+- **`run` кидає виняток**: не перехоплюється всередині `runReview`. Помилка проб'ється у викликача — це навмисно (баг у runner-обгортці не маскується під «провалений gate»).
+- **`fingerprint()` повертає `null`**: легітимний випадок (наприклад, worktree не git-репо); поле `fingerprint` у verdict-і просто буде `null`.
+- **`fingerprint()` кидає виняток на pass-гілці**: проб'ється у викликача; не обгортається в try/catch.
+
+## Залежності
+
+### Імпорти
+
+```js
+import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
+```
+
+Єдина зовнішня залежність модуля — функція `worktreeFingerprint` з `npm/scripts/utils/worktree-fingerprint.mjs`. Використовується лише як **значення за замовчуванням** для параметра `fingerprint` (через стрілку `() => worktreeFingerprint()`). Якщо викликач передає власну `fingerprint`-функцію, `worktreeFingerprint` не викликається.
+
+### Невидимі залежності (через ін'єкції)
+
+- `run` (передається ззовні) — фактичний запуск дочірніх процесів (`npx @nitra/cursor lint`, `npx @nitra/cursor coverage --changed`).
+- CLI `@nitra/cursor` — має бути доступний у `PATH` worktree-кореня (через `npx`).
+- Сабкоманди `lint` і `coverage` пакету `@nitra/cursor`, що внутрішньо тягнуть ESLint, Vitest, Stryker та логіку «changed files» з `changed-files.mjs`.
+
+### Зовнішні правила-документи
+
+- §5 spec — Quality Gates.
+- §8.4 spec — Level-1 «Суддя».
+- `flow verify` (`n-flow.mdc`) — пасивний турнікет.
+- `/n-coverage-fix`, `bun run coverage` — повний прогін coverage окремо.
+
+## Потік виконання / Використання
+
+### Типовий сценарій 1 — `flow verify` (пасивний турнікет)
+
+1. Користувач/CI запускає `flow verify` у worktree.
+2. Команда збирає ін'єкції:
+   - `run` — обгортка над `Bun.spawnSync` (синхронний запуск, capture stdout/stderr).
+   - `cwd` — корінь worktree.
+   - `gates` — `DEFAULT_GATES` (не перевизначається).
+   - `fingerprint` — default (`worktreeFingerprint`).
+3. Виклик `runReview({...})`.
+4. Аналіз verdict-у:
+   - `pass: true` → merge/commit дозволений; verdict разом із `fingerprint` зберігається у стан, щоб наступного разу детектити stale.
+   - `pass: false` → виводиться `failedOutput`, операція переривається.
+
+### Типовий сценарій 2 — per-step Ф4 (активний раннер)
+
+1. Dispatcher на фазі 4 циклу (після кожного кроку) викликає `runReview` для оцінки якості після зміни.
+2. Та ж сигнатура, ті ж `DEFAULT_GATES`.
+3. Verdict використовується для:
+   - прийняття рішення «крок успішний / відкотити»;
+   - формування feedback-у наступному LLM-кроку (через `failedOutput`).
+
+### Псевдокод інтеграції
+
+```js
+import { runReview, DEFAULT_GATES } from './reviewer.mjs'
+import { spawnSync } from 'node:child_process'
+
+const run = (cmd, args, opts) => {
+  const r = spawnSync(cmd, args, { ...opts, encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout, stderr: r.stderr }
+}
+
+const verdict = runReview({ run, cwd: process.cwd() })
+
+if (verdict.pass) {
+  saveState({ fingerprint: verdict.fingerprint, verdict })
+} else {
+  console.error(verdict.failedOutput)
+  process.exit(1)
+}
+```
+
+### Послідовність виконання (внутрішня)
+
+1. Ініціалізувати `results = []`, `failedOutput = null`.
+2. Для кожного `g ∈ gates` у порядку оголошення:
+   - 2.1. Викликати `run(g.cmd[0], g.cmd.slice(1), { cwd })`.
+   - 2.2. Обчислити `ok = (r?.status ?? 1) === 0`.
+   - 2.3. Додати `{ name: g.name, ok }` у `results`.
+   - 2.4. Якщо `!ok` — записати `failedOutput` із `stdout + '\n' + stderr` (trim → `null` якщо пусто) і **вийти з циклу**.
+3. Обчислити `pass = results.length === gates.length && results.every(x => x.ok)`.
+4. Якщо `pass` — викликати `fingerprint()`, інакше — `null`.
+5. Повернути `{ pass, gates: results, failedOutput, fingerprint }`.
+
+### Stale-семантика (роль fingerprint у часі)
+
+- Verdict із `fingerprint: 'abc123'` зберігається у стан Dispatcher-а.
+- Перед повторним використанням verdict-у викликач знову обчислює `worktreeFingerprint()` і порівнює.
+- Якщо відбитки збігаються → verdict ще валідний.
+- Якщо ні → файли у дереві змінились після pass-у; verdict **stale**, треба перепрогнати gate-и.
+- Цей механізм визначений §5 і реалізується **поза** `runReview` — модуль лише **постачає** fingerprint у момент успіху.
+
+## Rebuild Test
+
+Перевірка, що документація достатня для відтворення модуля з нуля:
+
+1. **Експорти й сигнатура** — `DEFAULT_GATES` (named, масив із двох об'єктів `{ name, cmd }` у фіксованому порядку lint→coverage), `runReview(input)` (named) із чотирма іменованими полями: `run`, `cwd`, `gates?`, `fingerprint?`.
+2. **Імпорт** — `worktreeFingerprint` з `../../utils/worktree-fingerprint.mjs`; використовується лише як значення за замовчуванням.
+3. **Канонічні команди gate-ів** — `['npx', '@nitra/cursor', 'lint']` та `['npx', '@nitra/cursor', 'coverage', '--changed']` (саме в такому порядку аргументів).
+4. **Алгоритм** — послідовний цикл for-of по `gates`, fail-fast із `break` на першому `!ok`, обчислення `ok` як `(r?.status ?? 1) === 0`.
+5. **`failedOutput`** — конкатенація `stdout` і `stderr` (defaultяться у `''`), розділювач `\n`, далі `trim()` та fallback на `null` через `|| null`.
+6. **`pass`** — комбінація двох умов: `results.length === gates.length` **і** `results.every(x => x.ok)` (друга умова критична для коректності, бо перша істинна вже на старті при порожньому `gates`).
+7. **`fingerprint` у verdict-і** — тернар `pass ? fingerprint() : null`; виклик ліниво.
+8. **Side-effect-free** — `runReview` сам не торкає FS/network/процеси; усе через ін'єкції.
+9. **Дефолти параметрів** — `gates = DEFAULT_GATES`, `fingerprint = () => worktreeFingerprint()`. Жодних дефолтів для `run` і `cwd` — обидва обов'язкові, відсутність призведе до runtime-помилки в тілі функції.
+10. **Структура verdict-у** — рівно чотири поля: `pass`, `gates`, `failedOutput`, `fingerprint`; жодних додаткових.