@nitra/cursor 3.21.1 → 3.23.0

package/scripts/dispatcher/lib/docs/flow-resolve.md

@@ -0,0 +1,267 @@
+# flow-resolve.mjs
+
+## Огляд
+
+Модуль `flow-resolve.mjs` реалізує **cwd-незалежний резолвер активного flow** для команд `spec`, `plan`, `verify`, `review`, `gate`, `release` (беклог адаптації #1).
+
+Призначення: знайти файл стану `*.flow.json` поточної задачі навіть тоді, коли команду запущено **не** з кореня worktree (наприклад, з кореня головного дерева репозиторію або з вкладеної підтеки worktree). Інакше функція `flowStatePath(cwd)` обчислила б хибний шлях і команда повідомила б «стану нема», хоча flow реально активний.
+
+Порядок резолвингу (відповідно до spec `2026-06-01-flow-cwd-state-resolution`):
+
+1. Якщо передано явний `branch` — формуємо шлях `<repoRoot>/.worktrees/<sanitizeBranch(branch)>.flow.json` і перевіряємо існування теки worktree.
+2. Швидкий шлях: якщо `cwd` сам уже є текою worktree і поряд лежить файл стану — беремо його (без виклику git).
+3. Toplevel-резолвинг: `git rev-parse --show-toplevel` від `cwd`; якщо toplevel розташований **безпосередньо** під `<repoRoot>/.worktrees/` і для нього існує стан — повертаємо його. Якщо стану нема — це проблема саме цього worktree, чужий активний flow **не** підтягуємо.
+4. Скан: якщо `cwd` поза будь-яким worktree (наприклад, головне дерево) — перебираємо `<repoRoot>/.worktrees/*.flow.json`, шукаючи статуси `in_progress`. Якщо рівно один — авторезолв; якщо кілька — помилка зі списком; якщо нуль — «стану нема».
+
+Резолвер **не пише** на диск і **не модифікує** стан. Усі залежності (`git`, FS-операції, `readState`) ін'єктуються через параметр `deps`, тож логіку можна тестувати без реального git-репозиторію.
+
+## Експорти / API
+
+| Експорт                                  | Тип             | Призначення                                               |
+| ---------------------------------------- | --------------- | --------------------------------------------------------- |
+| `resolveActiveFlowState(params?, deps?)` | named function  | Основна функція-резолвер; повертає об'єкт `ResolvedFlow`. |
+| `ResolvedFlow`                           | JSDoc-`typedef` | Тип-опис форми результату резолвингу.                     |
+
+Внутрішні (не експортуються) допоміжні функції: `realGit`, `mainRepoRoot`, `currentToplevel`, `notFound`.
+
+### Тип `ResolvedFlow`
+
+JSDoc-`typedef`, що описує форму результату:
+
+| Поле           | Тип              | Семантика                                                                                                     |
+| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
+| `statePath`    | `string \| null` | Абсолютний шлях до `.flow.json` або `null`, якщо стан не знайдено.                                            |
+| `worktreeDir`  | `string \| null` | Тека worktree (ефективний `cwd` для гейтів) або `null`.                                                       |
+| `label`        | `string \| null` | Мітка flow (sanitized branch) або `null`.                                                                     |
+| `autoResolved` | `boolean`        | `true`, якщо стан знайдено скануванням (тобто `cwd` був поза worktree, а активний flow знайшовся однозначно). |
+| `error`        | `string \| null` | Повідомлення для логу, якщо `statePath === null`; інакше `null`.                                              |
+
+### Константа `FLOW_STATE_SUFFIX`
+
+Внутрішня (не експортована) константа: `'.flow.json'`. Використовується для фільтрації імен файлів у теці `.worktrees/` під час скану та для обрізання суфікса при формуванні `label`.
+
+## Функції
+
+### `realGit(args, cwd)`
+
+Сигнатура: `function realGit(args: string[], cwd: string): { status: number, stdout: string }`
+
+Параметри:
+
+- `args` — масив аргументів для бінарника `git` (наприклад, `['worktree', 'list', '--porcelain']`);
+- `cwd` — робочий каталог, у якому запустити `git`.
+
+Повертає об'єкт `{ status, stdout }`:
+
+- `status` — exit-код процесу `git`; якщо `spawnSync` повернув `null` — підставляється `1`;
+- `stdout` — захоплений stdout у кодуванні `utf8`; якщо `null` — порожній рядок.
+
+Side effects: синхронний запуск дочірнього процесу `git` через `spawnSync`. Це **єдина** функція в модулі, що звертається до зовнішнього процесу; усе інше — чистий FS/обчислення. Використовується як **дефолтний** git-runner: при кожному виклику резолвера для конкретного `cwd` створюється стрілкова замикальна функція `args => realGit(args, cwd)`, якщо `deps.git` не передано.
+
+### `mainRepoRoot(git)`
+
+Сигнатура: `function mainRepoRoot(git: (args: string[]) => { status: number, stdout: string }): string | null`
+
+Параметри:
+
+- `git` — git-runner (для тестів — мок; у проді — обгортка над `realGit`).
+
+Повертає абсолютний шлях кореня **головного** worktree репозиторію або `null`, якщо неможливо встановити (git недоступний, не репо тощо).
+
+Алгоритм:
+
+1. Виконати `git worktree list --porcelain`.
+2. Якщо `status !== 0` — повернути `null`.
+3. У stdout знайти **перший** рядок, що починається з `worktree ` (це і є головне дерево за конвенцією porcelain-формату).
+4. Зрізати префікс `worktree ` і пробіли; якщо рядок непорожній — повернути; інакше `null`.
+
+Side effects: один git-виклик через переданий runner.
+
+### `currentToplevel(git)`
+
+Сигнатура: `function currentToplevel(git: (args: string[]) => { status: number, stdout: string }): string | null`
+
+Параметри:
+
+- `git` — git-runner.
+
+Повертає абсолютний шлях `toplevel`-теки для **поточного** worktree (`git rev-parse --show-toplevel`) або `null`, якщо команда впала або stdout порожній.
+
+Side effects: один git-виклик через переданий runner.
+
+### `resolveActiveFlowState(params?, deps?)`
+
+Сигнатура:
+
+```
+export function resolveActiveFlowState(
+  params?: { cwd?: string, branch?: string },
+  deps?: {
+    git?: (args: string[]) => { status: number, stdout: string },
+    exists?: (p: string) => boolean,
+    readState?: (p: string) => object | null,
+    readdir?: (d: string) => string[],
+    repoRoot?: string,
+  },
+): ResolvedFlow
+```
+
+Параметри:
+
+- `params.cwd` — робочий каталог, від якого вести резолвинг. За замовчуванням — результат `process.cwd()` (через `cwd as processCwd` з `node:process`).
+- `params.branch` — явна гілка, для якої треба знайти стан. Якщо задана, активний flow в інших worktree **ігнорується** — використовується «фіксований» режим.
+- `deps.git` — кастомний git-runner; за замовчуванням — `args => realGit(args, cwd)` (замикає `cwd` із `params`).
+- `deps.exists` — кастомна реалізація `existsSync`; за замовчуванням — `existsSync` з `node:fs`.
+- `deps.readState` — кастомний читач стану; за замовчуванням — `readState`, реекспортований із `./state-store.mjs` як `defaultReadState`.
+- `deps.readdir` — кастомне читання каталогу; за замовчуванням — функція, що повертає `readdirSync(d)` якщо тека існує, інакше `[]` (захист від ENOENT, коли `.worktrees/` ще не створено).
+- `deps.repoRoot` — наперед обчислений корінь репозиторію; якщо передано — обхід git для пошуку кореня пропускається.
+
+Повертає об'єкт `ResolvedFlow` (див. вище).
+
+Алгоритм (по гілках):
+
+1. **Локальний `resolveRoot()`** — стрілкова функція, що повертає `deps.repoRoot` або викликає `mainRepoRoot(git)`. Викликається лазиво — лише там, де потрібен корінь.
+
+2. **Гілка 1: явний `branch`.**
+   - Отримати `repoRoot` через `resolveRoot()`. Якщо `null` — повернути `notFound('стану нема — спершу `flow init`')`.
+   - `label = sanitizeBranch(branch)` (нормалізація імені гілки для імені файлу стану).
+   - `worktreeDir = worktreePaths(repoRoot, branch).checkout` — фізична тека worktree.
+   - Якщо `worktreeDir` **не** існує (`!exists(worktreeDir)`) — повернути `notFound` із повідомленням, що worktree для цієї гілки не знайдено (з підказкою перевірити назву або виконати `flow init`). Це захищає від ENOENT при подальших гейтах.
+   - Інакше повернути `{ statePath: flowStatePath(worktreeDir), worktreeDir, label, autoResolved: false, error: null }`.
+
+3. **Гілка 2: швидкий шлях без git.**
+   - Обчислити `direct = flowStatePath(cwd)`.
+   - Якщо файл існує — повернути `{ statePath: direct, worktreeDir: cwd, label: basename(cwd), autoResolved: false, error: null }`. Це типовий випадок: користувач у корені свого worktree.
+
+4. **Потрібен `repoRoot` через git** (`resolveRoot()`). Якщо `null` — повернути `notFound('стану нема — спершу `flow init`')`. Це безпечна деградація: якщо git недоступний, не лазимо далі.
+
+5. Обчислити `worktreesDir = join(repoRoot, '.worktrees')`.
+
+6. **Гілка 3: toplevel-резолвинг.**
+   - `top = currentToplevel(git)`.
+   - Якщо `top` визначено **і** `dirname(top) === worktreesDir` (тобто toplevel лежить безпосередньо під `<repoRoot>/.worktrees/`) — ми всередині worktree (можливо, з вкладеної підтеки):
+     - `statePath = flowStatePath(top)`.
+     - Якщо `exists(statePath)` — повернути `{ statePath, worktreeDir: top, label: basename(top), autoResolved: false, error: null }`.
+     - Інакше — `notFound('стану нема — спершу `flow init`')`. **Чужий** активний flow тут **не** підтягуємо: це проблема саме цього worktree.
+
+7. **Гілка 4: скан активних flow** (виконується, якщо `top` неможливо отримати або `dirname(top) !== worktreesDir`, тобто `cwd` поза будь-яким worktree — наприклад, у головному дереві).
+   - `active = []`.
+   - Для кожного `name` із `readdir(worktreesDir)`:
+     - Якщо ім'я не закінчується на `FLOW_STATE_SUFFIX` (`.flow.json`) — пропустити.
+     - Сформувати `statePath = join(worktreesDir, name)`.
+     - Спробувати `state = readState(statePath)`; будь-яка помилка (`catch`) — пропустити елемент (пошкоджений стан не валить скан).
+     - Якщо `state?.status === 'in_progress'`:
+       - `label = name.slice(0, -FLOW_STATE_SUFFIX.length)` — обрізати суфікс `.flow.json`.
+       - `worktreeDir = join(worktreesDir, label)`.
+       - Додати `{ statePath, worktreeDir, label }` у `active`.
+   - Якщо `active.length === 1` — повернути `{ ...active[0], autoResolved: true, error: null }`.
+   - Якщо `active.length > 1` — повернути `notFound` із форматованим списком: «кілька активних flow — уточни `--branch <гілка>` або `cd` у потрібний worktree:\n - <label1>\n - <label2>...».
+   - Інакше — `notFound('стану нема — спершу `flow init`')`.
+
+Side effects: тільки **читання** — `git`, `existsSync`, `readdirSync`, `readState`. Жодних записів на диск.
+
+### `notFound(error)`
+
+Сигнатура: `function notFound(error: string): ResolvedFlow`
+
+Параметри:
+
+- `error` — текст повідомлення для логу.
+
+Повертає об'єкт-«заглушку» з усіма полями стану, виставленими в `null`/`false`, і заданим `error`:
+
+```
+{ statePath: null, worktreeDir: null, label: null, autoResolved: false, error }
+```
+
+Side effects: немає (чиста функція).
+
+## Залежності
+
+### Стандартна бібліотека Node.js
+
+- `node:fs` — `existsSync`, `readdirSync` (дефолтні реалізації `exists`/`readdir`).
+- `node:child_process` — `spawnSync` (запуск `git`).
+- `node:path` — `basename`, `dirname`, `join` (формування та аналіз шляхів).
+- `node:process` — `cwd as processCwd` (дефолт для `params.cwd`).
+
+### Внутрішні модулі
+
+- `../../lib/worktree.mjs` — імпортуються:
+  - `sanitizeBranch(branch)` — нормалізація імені гілки → ім'я-мітка файлу стану;
+  - `worktreePaths(repoRoot, branch)` — повертає об'єкт із полем `checkout` (фізична тека worktree).
+- `./state-store.mjs` — імпортуються:
+  - `flowStatePath(worktreeDir)` — формує шлях файлу стану для заданої теки worktree;
+  - `readState as defaultReadState` — функція читання + парсингу JSON-стану; під час скану викликається у `try/catch`, тож може кидати помилку.
+
+### Зовнішні процеси
+
+- `git` (через `spawnSync`):
+  - `git worktree list --porcelain` — для знаходження кореня головного worktree;
+  - `git rev-parse --show-toplevel` — для визначення поточного worktree.
+
+## Потік виконання / Використання
+
+### Сценарій 1 — запуск із кореня worktree
+
+```
+cwd = /repo/.worktrees/feat-foo
+```
+
+1. `branch` не передано → Гілка 1 пропускається.
+2. `direct = flowStatePath('/repo/.worktrees/feat-foo')` існує → **повертається одразу** без виклику git. Це найшвидший і найчастіший випадок.
+
+### Сценарій 2 — запуск із підтеки worktree
+
+```
+cwd = /repo/.worktrees/feat-foo/src/lib
+```
+
+1. Гілка 1 — ні.
+2. Гілка 2 — `direct` не існує (бо `cwd` не корінь worktree).
+3. Через `mainRepoRoot(git)` отримуємо `/repo`; `worktreesDir = /repo/.worktrees`.
+4. `currentToplevel(git)` → `/repo/.worktrees/feat-foo`; `dirname === /repo/.worktrees` ✓ → повертаємо стан саме цього worktree.
+
+### Сценарій 3 — запуск із головного дерева (поза worktree)
+
+```
+cwd = /repo
+```
+
+1. Гілка 1 — ні.
+2. Гілка 2 — `flowStatePath('/repo')` не існує.
+3. `mainRepoRoot` → `/repo`; `worktreesDir = /repo/.worktrees`.
+4. `currentToplevel` → `/repo`; `dirname('/repo') !== '/repo/.worktrees'` → переходимо до скану.
+5. Скан `.worktrees/*.flow.json`:
+   - 1 із `status: in_progress` → `autoResolved: true`, повертається.
+   - 2+ → помилка зі списком кандидатів та пропозицією `--branch` або `cd`.
+   - 0 → `notFound('стану нема — спершу `flow init`')`.
+
+### Сценарій 4 — явний `--branch`
+
+```
+params = { branch: 'feat-foo' }
+```
+
+1. `repoRoot` отриманий → перевіряється існування фізичної теки worktree `feat-foo`.
+2. Якщо тека існує — повертається стан (навіть якщо файлу стану ще нема — це **очікуваний** шлях, користувач обере цю гілку).
+3. Якщо теки нема — `notFound` з підказкою перевірити назву / зробити `flow init`.
+
+### Сценарій 5 — git недоступний
+
+- Якщо `mainRepoRoot` повертає `null` (наприклад, бінарника git нема або це не репо) і прямий шлях через `cwd` теж не спрацював — повертаємо `notFound('стану нема — спершу `flow init`')`. Жодних падінь.
+
+### Контракт виклику з боку команд
+
+Команди `spec/plan/verify/review/gate/release` мають викликати `resolveActiveFlowState(...)` **на самому старті**, потім:
+
+- Якщо `result.statePath === null` — вивести `result.error` і завершитися ненульовим кодом.
+- Інакше використовувати:
+  - `result.statePath` — для читання/запису файлу стану через `state-store.mjs`;
+  - `result.worktreeDir` — як **ефективний** `cwd` для виконання гейтів (linter, tests, scripts) у потрібному worktree;
+  - `result.label` — для логів/повідомлень;
+  - `result.autoResolved` — щоб показати користувачу, що flow знайдено скануванням (корисно для UX: «авторезолв на гілку X»).
+
+### Тестування
+
+Усі зовнішні залежності (`git`, `exists`, `readState`, `readdir`, `repoRoot`) ін'єктуються через параметр `deps`. Це дає змогу повністю покрити функцію unit-тестами без реального git-репозиторію та без створення файлів на диску — достатньо передати моки, що повертають фіктивні `status`/`stdout`/булеві значення.

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

@@ -0,0 +1,231 @@
+# `gate.mjs` — реалізація команди `flow gate`
+
+## Огляд
+
+Модуль реалізує підкоманду `flow gate` диспатчера — структурований вердикт релізної готовності у стилі BMAD `qa-gate`, адаптованого до внутрішнього флоу проєкту. Скрипт **синтезує** два джерела сигналів, що накопичуються у файлі стану флоу (`.flow.json`):
+
+1. Механічні гейти, які заповнює крок `verify` (`state.gates` — масив `{ name, ok }`).
+2. Adversarial-зауваження, які залишає крок `review` (`state.review.findings` — масив об'єктів із полем `severity`).
+
+На виході формується єдиний вердикт `PASS | CONCERNS | FAIL`, числовий `score` у діапазоні `0..100` та список людиночитаних причин. Командa `gate` **не приймає рішень** за `verify` чи `review`, а лише агрегує їх — це забезпечує traceability «чому готово / не готово».
+
+Архітектурно модуль складається з двох частин:
+
+- `computeGate(state)` — **чиста** функція, повністю детермінована від вхідного стану, не торкається диска й часу. Призначена для unit-тестів без I/O-моків.
+- `gate(_rest, deps)` — async-обгортка, що читає стан з диска, викликає `computeGate`, фіксує результат як подію в `events.jsonl` і повертає exit-код для CLI. Усі залежності IO (`cwd`, `log`, `now`) ін'єктуються через `deps`, що робить функцію тестопридатною.
+
+## Експорти / API
+
+| Експорт       | Тип              | Призначення                             |
+| ------------- | ---------------- | --------------------------------------- |
+| `computeGate` | `function`       | Чистий синтез вердикту з об'єкта стану. |
+| `gate`        | `async function` | CLI-handler підкоманди `flow gate`.     |
+
+Модуль не має default-експорту. Внутрішня константа `PENALTY` (штрафи score) **не експортується** і є приватною деталлю реалізації.
+
+### `computeGate(state)`
+
+Сигнатура (JSDoc):
+
+```
+@param  {{ gates?: { name: string, ok: boolean }[],
+            review?: { findings?: { severity?: string }[] } }} state
+@returns {{ verdict: 'PASS' | 'CONCERNS' | 'FAIL',
+             score: number,
+             reasons: string[] }}
+```
+
+### `gate(_rest, deps)`
+
+Сигнатура (JSDoc):
+
+```
+@param  {string[]} _rest             аргументи CLI (не використовуються)
+@param  {{ cwd?: string,
+            log?: (m: string) => void,
+            now?: () => number,
+            branch?: string }}  [deps]  ін'єкції
+@returns {Promise<number>}            exit-код (FAIL → 1; PASS/CONCERNS → 0)
+```
+
+Параметр `_rest` зберігається в сигнатурі для уніфікації з рештою CLI-handlers диспатчера; підкреслення на початку позначає навмисне ігнорування. Крім задокументованих у JSDoc полів `deps`, реалізація читає також `deps.branch` — він передається в `resolveActiveFlowState`.
+
+## Функції
+
+### `computeGate(state)`
+
+- **Сигнатура:** `computeGate(state) → { verdict, score, reasons }`.
+- **Параметри:**
+  - `state.gates` (необов'язково) — масив об'єктів `{ name: string, ok: boolean }`. Якщо відсутній, береться `[]`.
+  - `state.review.findings` (необов'язково) — масив об'єктів із полем `severity` зі значенням `'high'` або `'med'` (інші значення ігноруються при підрахунку штрафів). Якщо відсутній — `[]`.
+- **Повертає:** об'єкт `{ verdict, score, reasons }`.
+  - `verdict` — рядок `'PASS'`, `'CONCERNS'` або `'FAIL'`.
+  - `score` — ціле число `0..100`, обмежене через `Math.max(0, Math.min(100, …))`.
+  - `reasons` — масив рядкових пояснень (можливо порожній при `PASS`).
+- **Side effects:** немає. Функція чиста, детермінована, без I/O і без використання глобального часу.
+
+**Алгоритм синтезу:**
+
+1. Розбиває `gates` на `failedGates = gates.filter(g => !g.ok)`.
+2. Розбиває `findings` на дві групи за `severity`: `high` і `med`.
+3. Прапор `noVerify = gates.length === 0` — стан, коли `verify` ще не запускався.
+4. Формує `reasons`:
+   - для кожного провального гейта: `gate «<name>» провалено`;
+   - якщо `high.length > 0`: `<N> high-severity review finding(s)`;
+   - якщо `med.length > 0`: `<N> med-severity review finding(s)`;
+   - якщо `noVerify`: `verify ще не запускався`.
+5. Визначає `verdict` за пріоритетом:
+   - `FAIL` — якщо є хоча б один провальний гейт **або** хоча б один `high`-finding;
+   - інакше `CONCERNS` — якщо є `med`-findings **або** `noVerify`;
+   - інакше `PASS`.
+6. Обраховує `penalty` як суму штрафів `PENALTY`:
+   - `failedGate = 40` за кожен провальний гейт;
+   - `high = 25` за кожен `high`-finding;
+   - `med = 8` за кожен `med`-finding;
+   - `noVerify = 15` (одноразово, якщо `gates` порожній).
+7. `score = max(0, min(100, 100 - penalty))`.
+
+**Інваріанти:**
+
+- `FAIL` ⇒ `score < 100` (`penalty ≥ 25` гарантовано через high або failedGate ≥ 40).
+- `PASS` ⇒ `penalty = 0` ⇒ `score = 100`.
+- `CONCERNS` досяжний при `penalty > 0` без `failedGates` і без `high`.
+- `score` ніколи не виходить за `[0, 100]`.
+
+### `gate(_rest, deps = {})`
+
+- **Сигнатура:** `async gate(_rest, deps) → Promise<number>`.
+- **Параметри:**
+  - `_rest` — масив рядків (CLI-аргументи), ігнорується.
+  - `deps.cwd` — поточна робоча директорія; default — `process.cwd()`.
+  - `deps.log` — функція логування; default — `console.error`.
+  - `deps.now` — провайдер часу `() => number`; default — `Date.now`.
+  - `deps.branch` — додаткова підказка для `resolveActiveFlowState` (необов'язково).
+- **Повертає:** `Promise<number>` — exit-код процесу:
+  - `1` — якщо стан недоступний (немає активного флоу або `flow init` ще не виконувався) або вердикт `FAIL`;
+  - `0` — для `PASS` і `CONCERNS`.
+- **Side effects:**
+  - Викликає `resolveActiveFlowState` (може читати worktree/гілку).
+  - Викликає `readState(statePath)` — синхронне читання `.flow.json`.
+  - Викликає `recordTransition(...)` — мутація `.flow.json` і дописування в `events.jsonl` (через `flowEventsPath(cwd)`).
+  - Логування в `deps.log` (за замовчуванням stderr).
+
+**Покроковий потік:**
+
+1. Розв'язує дефолтні залежності: `cwd0`, `log`, `now`.
+2. `resolveActiveFlowState({ cwd: cwd0, branch })` визначає активний флоу:
+   - якщо `resolved.statePath` пустий — логує `gate: <error>` і повертає `1`;
+   - якщо `resolved.autoResolved` — логує повідомлення `flow: авторезолвлено активний flow «<label>» (cwd поза worktree)`.
+3. Підставляє `cwd = resolved.worktreeDir ?? cwd0` і `statePath = resolved.statePath`.
+4. Читає стан `readState(statePath)`; якщо `null/undefined` — логує `gate: стану нема — спершу `flow init``і повертає`1`.
+5. Викликає `computeGate(state)` → `result`.
+6. Викликає `recordTransition` з:
+   - шляхами `{ statePath, eventsPath: flowEventsPath(cwd) }`,
+   - подією `{ type: 'gate', verdict: result.verdict }`,
+   - редьюсером `s => ({ ...s, gate: { ...result, at: new Date(now()).toISOString() } })` — додає до стану секцію `gate` з `verdict`/`score`/`reasons`/`at` (ISO-таймстемп);
+   - провайдером часу `now`.
+7. Логує рядок `gate: <VERDICT> (score <N>)`, потім по `  · <reason>` для кожної причини.
+8. Повертає `1`, якщо `result.verdict === 'FAIL'`, інакше `0`.
+
+## Залежності
+
+### Зовнішні (Node.js core)
+
+- `node:process` — імпорт `cwd as processCwd` для дефолтного значення `deps.cwd`.
+
+### Внутрішні модулі диспатчера
+
+- `./events.mjs` — функція `flowEventsPath(cwd)` будує шлях до файлу подій `events.jsonl` поточного флоу.
+- `./state-store.mjs`:
+  - `readState(statePath)` — синхронне читання `.flow.json` (повертає `null`, якщо нема);
+  - `recordTransition({ statePath, eventsPath }, event, reducer, now)` — атомарна мутація стану + лог подій.
+- `./flow-resolve.mjs` — `resolveActiveFlowState({ cwd, branch }, deps)` визначає активний worktree/гілку/`statePath`; повертає поля `statePath`, `worktreeDir`, `autoResolved`, `label`, `error`.
+
+### Глобальні
+
+- `console.error` — дефолтний логер (замінюється через `deps.log` у тестах).
+- `Date.now`, `new Date(...).toISOString()` — джерело таймстемпів (час ін'єктується через `deps.now`, але `new Date(...).toISOString()` працює з результатом).
+
+## Потік виконання / Використання
+
+### Інтеграція в CLI
+
+`gate` реєструється в основному диспатчері `flow` як handler підкоманди `gate`. Виклик відбувається у форматі:
+
+```
+flow gate
+```
+
+Додаткові позиційні аргументи не зчитуються (`_rest` ігнорується).
+
+### Типовий ланцюжок флоу
+
+```
+flow init      → створює .flow.json
+flow verify    → заповнює state.gates
+flow review    → заповнює state.review.findings
+flow gate      → агрегує → state.gate = { verdict, score, reasons, at }
+```
+
+### Сценарії exit-коду
+
+| Сценарій                  | Лог                                     | Exit |
+| ------------------------- | --------------------------------------- | ---- |
+| Активний флоу не знайдено | `gate: <error>`                         | `1`  |
+| `.flow.json` відсутній    | `gate: стану нема — спершу `flow init`` | `1`  |
+| `verdict = FAIL`          | `gate: FAIL (score …)` + причини        | `1`  |
+| `verdict = CONCERNS`      | `gate: CONCERNS (score …)` + причини    | `0`  |
+| `verdict = PASS`          | `gate: PASS (score 100)`                | `0`  |
+
+### Приклад чистого використання `computeGate`
+
+```js
+import { computeGate } from './gate.mjs'
+
+const state = {
+  gates: [
+    { name: 'lint', ok: true },
+    { name: 'test', ok: false }
+  ],
+  review: { findings: [{ severity: 'med' }] }
+}
+
+computeGate(state)
+// → { verdict: 'FAIL', score: 52, reasons: [
+//     'gate «test» провалено',
+//     '1 med-severity review finding(s)'
+//   ] }
+```
+
+### Приклад тестування `gate` через ін'єкції
+
+```js
+import { gate } from './gate.mjs'
+
+const logs = []
+const code = await gate([], {
+  cwd: '/tmp/fixture',
+  log: m => logs.push(m),
+  now: () => 1_700_000_000_000
+})
+
+// code === 0 | 1
+// logs містить рядки виду 'gate: PASS (score 100)' / '  · …'
+```
+
+### Записи в `.flow.json`
+
+Після успішного виконання у стані з'являється секція:
+
+```json
+{
+  "gate": {
+    "verdict": "CONCERNS",
+    "score": 92,
+    "reasons": ["1 med-severity review finding(s)"],
+    "at": "2024-01-01T00:00:00.000Z"
+  }
+}
+```
+
+Подія `{ type: 'gate', verdict }` дописується в `events.jsonl` через `recordTransition`.