@nitra/cursor 3.22.0 → 3.23.1

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

@@ -0,0 +1,167 @@
+# budget.mjs
+
+## Огляд
+
+Модуль `budget.mjs` реалізує **запобіжник бюджету** (budget guard) для автономного режиму диспатчера (відповідно до spec §9.4). Його основна задача — обмежити кількість викликів зовнішнього API, які робить `SubagentRunner`, щоб запобігти неконтрольованим витратам у середовищах, де нема людини-оператора для ручної зупинки (наприклад, на сервері або в CI).
+
+Модуль реалізує патерн **декоратор/обгортка**: приймає базовий runner, що має метод `runStep`, і повертає функціонально еквівалентний об'єкт, який додатково:
+
+- веде лічильник викликів `runStep`;
+- порівнює лічильник із заданим лімітом `maxApiCalls` перед кожним викликом;
+- кидає кастомну помилку `BudgetExceeded` при перевищенні ліміту;
+- логує кожен виклик через переданий колбек `log`.
+
+Окремо експортується клас помилки `BudgetExceeded`, який споживачі модуля (зокрема `run`-функція диспатчера, §9.4) можуть ловити для коректного завершення з відповідним статусом.
+
+У коментарях файлу зазначено, що параметр `maxCostUsd` (бюджет за вартістю в доларах) поки не реалізований і запланований на майбутнє — на момент написання модуль рахує лише факти виклику, а не споживані токени чи вартість.
+
+## Експорти / API
+
+Модуль експортує два ідентифікатори (обидва — іменовані експорти, default-експорту немає):
+
+| Експорт          | Тип                   | Призначення                                                                                      |
+| ---------------- | --------------------- | ------------------------------------------------------------------------------------------------ |
+| `BudgetExceeded` | `class extends Error` | Кастомний клас помилки, що сигналізує про вичерпання бюджету `maxApiCalls`.                      |
+| `withBudget`     | функція               | Фабрика, що обгортає переданий runner лічильником і поверненням нового runner-сумісного об'єкта. |
+
+## Функції
+
+### `class BudgetExceeded extends Error`
+
+**Сигнатура:** `class BudgetExceeded extends Error {}`
+
+**Опис:** Маркерний підклас стандартної `Error`. Тіло класу порожнє — використовується виключно для відрізнення цього типу помилки від інших через `instanceof BudgetExceeded` або зіставлення в `try/catch`. Конструктор успадковується від `Error` і приймає рядок-повідомлення.
+
+**Параметри:**
+
+- `message` (string, через `super`) — текст помилки. У місці кидання передається рядок виду `budget: вичерпано maxApiCalls=<N>`.
+
+**Side effects:** жодних.
+
+**Кидає:** не застосовно (це сам клас помилки, його екземпляр кидається в `withBudget`).
+
+### `withBudget(runner, opts)`
+
+**Сигнатура:**
+
+```
+withBudget(
+  runner: { backend?: string, runStep: (prompt: string, opts?: object) => object },
+  opts?: { maxApiCalls?: number, log?: (m: string) => void }
+): {
+  backend: string,
+  runStep: (prompt: string, opts?: object) => Promise<object>,
+  readonly calls: number
+}
+```
+
+**Параметри:**
+
+- `runner` (object, обовʼязковий) — базовий runner, який потрібно обмежити бюджетом. Інтерфейс:
+  - `backend?: string` — опційний ідентифікатор бекенду (пробросовується у поверненому обʼєкті).
+  - `runStep(prompt, opts?) => object` — метод виконання одного кроку (виклику API). Повертати може як значення, так і `Promise`; в обгортці він викликається без `await`, але метод обгортки оголошено `async`, тож результат буде успішно "розгорнуто" викликаючою стороною.
+- `opts` (object, опційний, за замовчуванням `{}`) — налаштування бюджету:
+  - `maxApiCalls?: number` — максимально дозволена кількість викликів `runStep`. Якщо не передано, використовується `Number.POSITIVE_INFINITY` (фактично — без ліміту).
+  - `log?: (m: string) => void` — колбек логування. Якщо не передано, використовується no-op `() => {}`.
+
+**Повертає:** новий обʼєкт-обгортку з такими членами:
+
+- `backend` — копія значення `runner.backend` (один до одного, через звичайне присвоєння у літералі). Допомагає вищим шарам визначати, з яким бекендом працює runner, без розпаковки обгортки.
+- `get calls()` — getter (read-only ззовні), що повертає поточне значення внутрішньої змінної `calls` (кількість зроблених викликів). Дозволяє споживачам читати лічильник, але не дає його модифікувати.
+- `async runStep(prompt, stepOpts)` — обгортка над `runner.runStep`. Алгоритм:
+  1. Якщо `calls >= maxApiCalls` — кидає `new BudgetExceeded('budget: вичерпано maxApiCalls=<maxApiCalls>')`. Перевірка виконується **до** інкременту, тобто `maxApiCalls=N` дозволяє рівно `N` викликів `runStep`, які успішно дійдуть до делегування у внутрішній runner.
+  2. Інкрементує `calls` на 1.
+  3. Викликає `log` із повідомленням виду `budget: API-виклик <calls>/<maxApiCalls>`.
+  4. Повертає результат `runner.runStep(prompt, stepOpts)` (як значення промісу, бо метод `async`).
+
+**Side effects:**
+
+- Мутує закриту (замкнену в замиканні) змінну `calls` — інкремент на кожен валідний виклик.
+- Викликає переданий `log` як побічний ефект логування (виклик відбувається **після** інкременту, тому в логах перший виклик буде `1/<maxApiCalls>`).
+- Делегує виклик `runner.runStep`, що має власні side effects (мережа, файлова система тощо — залежно від реалізації runner).
+
+**Кидає:**
+
+- `BudgetExceeded` — коли бюджет уже вичерпано на момент чергового виклику `runStep`. У цьому випадку внутрішній `runner.runStep` **не** викликається.
+- Все, що кидає `runner.runStep`, проходить наскрізь без обгортання (бо результат повертається, а не `await`-иться у tryблоку).
+
+**Особливості реалізації:**
+
+- Лічильник зберігається в локальній змінній `let calls`, доступ ззовні — лише через getter, що робить значення фактично read-only. Прямого сетера немає.
+- `maxApiCalls ?? Number.POSITIVE_INFINITY` — використання nullish coalescing: значення `0` залишається `0` (тобто 0 викликів дозволено = одразу `BudgetExceeded`). Тільки `undefined`/`null` замінюються на `Infinity`.
+- `log` за замовчуванням — функція-заглушка `() => {}`, тож виклик безпечний у будь-якому випадку.
+- Перевірка `calls >= maxApiCalls` робиться перед інкрементом: для `maxApiCalls=3` третій виклик пройде (бо до інкременту `calls=2 < 3`), четвертий — впаде з `BudgetExceeded`.
+
+## Залежності
+
+**Зовнішні (npm/standard):** жодних — модуль не імпортує нічого.
+
+**Внутрішні (проєктні):** жодних — модуль самодостатній.
+
+**Глобальні залежності runtime:**
+
+- `Error` — стандартний клас JavaScript (базовий для `BudgetExceeded`).
+- `Number.POSITIVE_INFINITY` — стандартна константа.
+
+**Стандарт мови:** використовуються ES-modules (`export`), `class` (ES2015), `async`/`await` (ES2017), nullish coalescing `??` (ES2020), getter у літералі обʼєкта (ES5+). Файл має розширення `.mjs`, що явно вказує Node.js на ESM-режим.
+
+## Потік виконання / Використання
+
+### Загальний потік
+
+1. Споживач (наприклад, диспатчер у `run`) створює базовий `SubagentRunner` із власним методом `runStep`.
+2. Перед запуском автономного циклу runner обгортається: `const guarded = withBudget(runner, { maxApiCalls: 50, log: logger.info })`.
+3. У циклі дисперчера викликається `await guarded.runStep(prompt, opts)` стільки разів, скільки потрібно.
+4. Поточне споживання можна читати через `guarded.calls`.
+5. При перевищенні `maxApiCalls` наступний `runStep` кине `BudgetExceeded`, який споживач ловить і завершує сесію з відповідним статусом (§9.4).
+
+### Приклад використання
+
+```js
+import { withBudget, BudgetExceeded } from './budget.mjs'
+
+const baseRunner = {
+  backend: 'claude',
+  async runStep(prompt, opts) {
+    // ... виклик API
+    return { text: '...', tokens: 123 }
+  }
+}
+
+const runner = withBudget(baseRunner, {
+  maxApiCalls: 10,
+  log: msg => console.log(msg)
+})
+
+try {
+  for (const step of plan) {
+    const result = await runner.runStep(step.prompt)
+    // ... обробка
+  }
+} catch (err) {
+  if (err instanceof BudgetExceeded) {
+    console.error('Зупинка: бюджет вичерпано після', runner.calls, 'викликів')
+    process.exit(2)
+  }
+  throw err
+}
+```
+
+### Контракт з вищими шарами
+
+- **`SubagentRunner`** має надавати `{ backend, runStep(prompt, opts) }`. Обгортка не вимагає інших полів; усе, що поза `backend` і `runStep`, **губиться** при обгортанні (їх немає у поверненому літералі).
+- **`run`-функція (§9.4)** має ловити `BudgetExceeded` окремо від інших помилок, інакше бюджет проявиться як звичайний краш.
+- **Тестування:** клас `BudgetExceeded` пустий, тож порівнювати краще через `instanceof`, а не через `err.name` чи `err.constructor.name` (хоча обидва теж працюватимуть стандартно для підкласу `Error`).
+
+### Граничні випадки
+
+- `maxApiCalls: 0` — будь-який перший виклик `runStep` одразу кидає `BudgetExceeded`.
+- `maxApiCalls: undefined` (опція не передана) — фактично без обмеження (Infinity).
+- `maxApiCalls: Infinity` явно — те саме, без обмеження.
+- `opts` не переданий — використовуються всі дефолти (`Infinity` і no-op log).
+- `runner.backend === undefined` — у поверненому обʼєкті `backend` буде `undefined` (типізація показує `string`, але рантайм цьому не перешкоджає).
+- `runner.runStep` синхронний — все одно повертає Promise, бо обгортка `async`.
+
+### Звʼязок зі spec
+
+Файл явно посилається на **spec §9.4** ("Budget guard для автономного режиму"). Логіка цього модуля є реалізацією контракту, описаного в специфікації: лічильник API-викликів + кастомна помилка `BudgetExceeded` як механізм аварійного виходу.

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

@@ -0,0 +1,196 @@
+# capability.mjs
+
+## Огляд
+
+Модуль `capability.mjs` реалізує **Capability Router** — шар резолюції режиму оркестрації для підкоманди `flow` диспетчера `n-cursor`. Завдання модуля — відповісти на запитання: «у якому режимі (`native` чи `polyfill`) виконувати flow для оголошеної моделі LLM?».
+
+Ключові архітектурні рішення модуля:
+
+- **Жодної рантайм-детекції моделі.** Модель не вгадується з оточення/процесу — її потрібно **явно оголосити** (CLI-прапорець, env, config). Це відповідає вимозі spec §2.2 проєкту.
+- **Чисті функції без I/O.** Усі вхідні джерела (`args`, `env`, `config`, `matrix`, `hasRunner`) приходять параметрами ззовні. Модуль не читає файлову систему, не звертається до мережі та не використовує `process.*` напряму. Завдяки цьому функції тривіально тестуються без моків.
+- **Розділення відповідальності.** Сам модуль лише **резолвить** режим і повідомляє про можливість запуску `polyfill`. Власне кидання помилок (`fail`) та інтеграція з runner-ом виконуються caller-ом — `polyfill` без доступного `SubagentRunner` (§15.1) не може стартувати, але рішення про помилку приймається вище за стеком.
+
+Модуль використовується як read-only утиліта диспетчером: спочатку парситься CLI-прапорець `--model`, потім збирається оголошена модель за пріоритетом, далі береться режим оркестрації з `capability-matrix`, і нарешті перевіряється, чи доступний `SubagentRunner` для polyfill-шляху.
+
+## Експорти / API
+
+| Експорт                           | Тип                                | Опис                                                                                                                                  |
+| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `DEFAULT_ORCHESTRATION`           | константа: `string` (`'polyfill'`) | Дефолтний режим оркестрації, що повертається, коли в `matrix` немає інформації для моделі і не задано `matrix.default.orchestration`. |
+| `parseModelFlag(args)`            | функція                            | Витягує значення прапорця `--model <value>` з масиву argv.                                                                            |
+| `declaredModel(sources)`          | функція                            | Повертає оголошену модель за пріоритетом CLI > env > config.                                                                          |
+| `orchestrationFor(model, matrix)` | функція                            | Резолвить режим оркестрації (`'native'                                                                                                | 'polyfill'`) для оголошеної моделі за матрицею. |
+| `polyfillStartable(ctx)`          | функція                            | Перевіряє, чи доступний `SubagentRunner`, необхідний для старту polyfill-режиму.                                                      |
+
+Усі експорти — `named exports`; `default export` відсутній.
+
+## Функції
+
+### `parseModelFlag(args)`
+
+**Сигнатура:** `parseModelFlag(args: string[]): string | null`
+
+**Параметри:**
+
+- `args` — масив рядків, що представляє argv підкоманди `flow` (без імені виконуваного файлу). Зазвичай це частина `process.argv`, передана у диспетчер.
+
+**Повертає:**
+
+- `string` — значення, що йде безпосередньо за токеном `--model` в argv.
+- `null` — якщо токен `--model` відсутній або є останнім елементом масиву (тобто значення за ним немає).
+
+**Алгоритм:**
+
+1. Знайти індекс першого входження рядка `'--model'` через `Array.prototype.indexOf`.
+2. Якщо індекс не `-1` **і** наступний елемент існує (`i + 1 < args.length`) — повернути `args[i + 1]`.
+3. Інакше — повернути `null`.
+
+**Side effects:** жодних. Вхідний масив не мутується, лише читається.
+
+**Зауваги:**
+
+- Розпізнається лише форма `--model <value>` через пробіл. Форма `--model=value` цією функцією **не** підтримується.
+- Враховується лише перше входження `--model` (наслідок `indexOf`).
+- Якщо аргумент після `--model` сам є прапорцем (наприклад, `--model --foo`), він однаково буде повернутий — валідація формату значення не виконується.
+
+### `declaredModel(sources)`
+
+**Сигнатура:** `declaredModel(sources?: { cliModel?: string | null, envModel?: string | null, configModel?: string | null }): string | null`
+
+**Параметри (об’єкт-деструктуризація з дефолтами `null`):**
+
+- `cliModel` — модель, отримана з CLI (зазвичай результат `parseModelFlag`). Найвищий пріоритет.
+- `envModel` — модель з env-змінної (за конвенцією проєкту — `N_CURSOR_FLOW_MODEL`). Середній пріоритет.
+- `configModel` — модель з конфігураційного файла (ключ `flow.model`). Найнижчий пріоритет.
+
+Усі три поля **опціональні**; виклик без аргументів (`declaredModel()`) валідний завдяки дефолту `= {}`.
+
+**Повертає:**
+
+- `string` — перше істинне (truthy) значення серед `cliModel`, `envModel`, `configModel` у вказаному порядку.
+- `null` — якщо всі три джерела falsy (`null`, `undefined`, `''`).
+
+**Алгоритм:** короткозамкнений ланцюг `cliModel || envModel || configModel || null`.
+
+**Side effects:** жодних.
+
+**Зауваги:** оскільки використовується `||`, **порожній рядок** `''` трактується як «не оголошено» і пропускається — це узгоджується з намірами модуля (модель повинна бути не лише визначена, а й непорожня).
+
+### `orchestrationFor(model, matrix)`
+
+**Сигнатура:** `orchestrationFor(model: string | null, matrix: { models?: Record<string, { orchestration?: string }>, default?: { orchestration?: string } }): 'native' | 'polyfill'`
+
+**Параметри:**
+
+- `model` — оголошена модель (зазвичай результат `declaredModel`). Може бути `null`.
+- `matrix` — capability-matrix:
+  - `matrix.models` — мапа `модель → { orchestration }` з режимом для конкретних моделей.
+  - `matrix.default.orchestration` — фолбек-режим для невідомих/неоголошених моделей.
+
+**Повертає:** літеральний рядок `'native'` або `'polyfill'` (типи з JSDoc; у реальності повертається будь-яке рядкове значення, прочитане з матриці, але інваріант протоколу — саме ці два).
+
+**Алгоритм каскадного фолбеку:**
+
+1. Якщо `model` truthy **і** є `matrix.models` — узяти `entry = matrix.models[model]`; інакше `entry = null`.
+2. Повернути перше істинне з трьох:
+   - `entry?.orchestration` — режим, прописаний для конкретної моделі;
+   - `matrix?.default?.orchestration` — дефолт із самої матриці;
+   - `DEFAULT_ORCHESTRATION` — глобальний дефолт модуля (`'polyfill'`).
+
+**Side effects:** жодних. Матриця читається ad hoc без копіювання.
+
+**Зауваги:**
+
+- Функція стійка до `null`/`undefined` як `matrix`, так і `matrix.models`/`matrix.default` завдяки явним перевіркам та операторам `&&`.
+- Невідома модель (відсутня в `matrix.models`) автоматично потрапляє в гілку `matrix.default` → `DEFAULT_ORCHESTRATION`. Це означає, що нові/незареєстровані моделі за замовчуванням підуть через `polyfill` (за наявності runner-а).
+
+### `polyfillStartable(ctx)`
+
+**Сигнатура:** `polyfillStartable(ctx: { hasRunner: boolean }): boolean`
+
+**Параметри:**
+
+- `ctx.hasRunner` — прапорець наявності `SubagentRunner` у середовищі (відповідно до §15.1 spec). Тип повинен бути саме `boolean`.
+
+**Повертає:**
+
+- `true` — якщо `ctx.hasRunner === true` (strict equality).
+- `false` — у будь-якому іншому випадку (`false`, `undefined`, truthy-не-`true`, тощо).
+
+**Алгоритм:** одна перевірка `hasRunner === true`.
+
+**Side effects:** жодних.
+
+**Зауваги:** strict-перевірка свідома — модуль не приймає «приблизно правда» значення (`1`, `'yes'`, об’єкти runner-а тощо). Це змушує caller-а передавати дискретний boolean-прапорець, що дисциплінує контракт.
+
+## Залежності
+
+**Імпорти:** жодних. Модуль **самодостатній** — не залежить ні від npm-пакетів, ні від інших файлів проєкту.
+
+**Глобали / середовище:** не використовуються. Зокрема, не читається `process.argv`, `process.env`, файлова система, мережа.
+
+**Споживачі (caller-и):** модуль очікувано викликається з реалізації підкоманди `flow` диспетчера (`npm/scripts/dispatcher/...`), яка:
+
+1. збирає `args` з `process.argv`;
+2. підставляє `process.env.N_CURSOR_FLOW_MODEL` як `envModel`;
+3. читає `flow.model` з config-файла як `configModel`;
+4. вантажить `capability-matrix` (ймовірно, із статичного JSON/JS);
+5. визначає `hasRunner` за наявністю `SubagentRunner` у рантаймі;
+6. за результатом `orchestrationFor` + `polyfillStartable` або стартує flow, або кидає помилку.
+
+## Потік виконання / Використання
+
+Типовий ланцюг викликів caller-а:
+
+```js
+import {
+  parseModelFlag,
+  declaredModel,
+  orchestrationFor,
+  polyfillStartable,
+  DEFAULT_ORCHESTRATION
+} from './capability.mjs'
+
+// 1. CLI-парсинг
+const cliModel = parseModelFlag(args)
+
+// 2. Резолюція оголошеної моделі за пріоритетом
+const model = declaredModel({
+  cliModel,
+  envModel: process.env.N_CURSOR_FLOW_MODEL ?? null,
+  configModel: config?.flow?.model ?? null
+})
+
+// 3. Режим оркестрації за матрицею
+const mode = orchestrationFor(model, capabilityMatrix)
+
+// 4. Перевірка можливості старту polyfill
+if (mode === 'polyfill' && !polyfillStartable({ hasRunner })) {
+  throw new Error('polyfill requires SubagentRunner (spec §15.1)')
+}
+
+// 5. Старт flow у режимі mode
+startFlow({ mode, model })
+```
+
+**Інваріанти потоку:**
+
+- Якщо модель **не оголошена** в жодному з трьох джерел, `declaredModel` повертає `null`. `orchestrationFor(null, matrix)` пропустить `matrix.models` і впаде на `matrix.default` або `DEFAULT_ORCHESTRATION = 'polyfill'`. Тобто за замовчуванням flow без оголошеної моделі піде через `polyfill` — і вимагатиме `SubagentRunner`.
+- Caller відповідає за **fail-fast** у разі `mode === 'polyfill' && !hasRunner`. Сам модуль помилок не кидає.
+- `DEFAULT_ORCHESTRATION = 'polyfill'` означає: «дефолт — мати polyfill доступним»; це сумісно з ідеєю, що `polyfill` має «працювати з будь-якою моделлю» **лише** за наявності runner-а.
+
+**Таблиця рішень `orchestrationFor`:**
+
+| `model`          | `matrix.models[model]`          | `matrix.default.orchestration` | Результат                              |
+| ---------------- | ------------------------------- | ------------------------------ | -------------------------------------- |
+| `'modelA'`       | `{ orchestration: 'native' }`   | будь-що                        | `'native'`                             |
+| `'modelB'`       | `{ orchestration: 'polyfill' }` | будь-що                        | `'polyfill'`                           |
+| `'unknownModel'` | відсутній                       | `'native'`                     | `'native'`                             |
+| `'unknownModel'` | відсутній                       | `'polyfill'`                   | `'polyfill'`                           |
+| `'unknownModel'` | відсутній                       | відсутній                      | `DEFAULT_ORCHESTRATION` (`'polyfill'`) |
+| `null`           | (не дивимось)                   | `'native'`                     | `'native'`                             |
+| `null`           | (не дивимось)                   | відсутній                      | `DEFAULT_ORCHESTRATION` (`'polyfill'`) |
+
+## Rebuild Test
+
+На основі цієї документації модуль `capability.mjs` можна повністю відтворити: він складається з однієї константи `DEFAULT_ORCHESTRATION = 'polyfill'` та чотирьох чистих експортних функцій (`parseModelFlag`, `declaredModel`, `orchestrationFor`, `polyfillStartable`) з описаними вище сигнатурами, алгоритмами та інваріантами; жодних імпортів, жодного I/O, жодного default-export — тільки named exports.

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

@@ -0,0 +1,210 @@
+# commands.mjs
+
+## Огляд
+
+Модуль `commands.mjs` реалізує handler-и підкоманд CLI `n-cursor flow` згідно зі специфікацією §8 (Пасивний Турнікет / Flow). Він є диспетчерською точкою для Фази Ф2 робочого потоку — підкоманд `init`, `verify` та `release`, — а також надає допоміжні утиліти: реальний sync-runner `realRun`, гарантію наявності worktree `ensureWorktree` та інференс воркспейсу за зміненими файлами `matchChangedWorkspaces`.
+
+Усі побічні ефекти (виконання процесів, логування, обчислення fingerprint, час) реалізовані як ін'єктовані залежності в `deps`, тож логіку модуля можна тестувати без реальних `git`, `npx` чи годинника. Це частина архітектури «командна логіка + чистий ядро». Підкоманди `run` / `resume` / `cancel` / `repair` зі специфікації належать Фазі Ф4 і в цьому файлі ще не реалізовані.
+
+Модуль є ESM (`.mjs`), використовує імпорти Node.js (`node:child_process`, `node:path`, `node:process`) і не має станового глобалу — стан тримається у JSON-файлах `.flow.json` (через `state-store.mjs`).
+
+## Експорти / API
+
+| Експорт                                               | Тип              | Призначення                                                                                                                 |
+| ----------------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| `realRun(cmd, args, opts?)`                           | `function`       | Реальний sync-обгортка над `spawnSync` із захопленням stdout/stderr.                                                        |
+| `ensureWorktree(rest, deps?)`                         | `function`       | Парсить аргументи `<branch> "<опис>"`, гарантує worktree (детектить існуючу ізоляцію або створює новий), повертає метадані. |
+| `init(rest, deps?)`                                   | `async function` | Handler `flow init`: ізоляція + первинна ініціалізація `.flow.json`.                                                        |
+| `verify(_rest, deps?)`                                | `async function` | Handler `flow verify`: Quality Gates («Суддя») у поточному worktree з толерантністю до відсутності стану.                   |
+| `matchChangedWorkspaces(subWorkspaces, changedFiles)` | `function`       | Чистий хелпер: підмножина воркспейсів, у яких є зміни (з прив'язкою до найглибшого збігу).                                  |
+| `release(rest, deps?)`                                | `async function` | Handler `flow release`: генерує `.changes` через `n-cursor change` і пише completion snapshot.                              |
+
+Усі async handler-и повертають Promise<number> — exit code (0 — ок, 1 — помилка). Решта — синхронні.
+
+## Функції
+
+### `realRun(cmd, args, opts = {})`
+
+- Сигнатура: `(cmd: string, args: string[], opts?: object) => { status: number, stdout: string, stderr: string }`.
+- Параметри:
+  - `cmd` — назва/шлях виконуваного файлу.
+  - `args` — масив аргументів.
+  - `opts` — додаткові опції для `spawnSync` (наприклад, `cwd`). Завжди примусово `encoding: 'utf8'`.
+- Повертає об'єкт із полями `status` (1, якщо `spawnSync` повернув `null` через сигнал/помилку запуску), `stdout`, `stderr`.
+- Side effects: синхронно стартує процес ОС.
+
+### `inLinkedWorktree(run, cwd)` (внутрішня)
+
+- Сигнатура: `(run, cwd: string) => boolean`.
+- Логіка: викликає `git rev-parse --git-dir`, `--git-common-dir`, `--show-superproject-working-tree`. Worktree вважається «лінкованим», якщо обидва git-dir команди повернули код 0, це **не** submodule, і `git-dir !== git-common-dir`.
+- Повертає `true`, якщо процес виконується всередині linked worktree (не основного checkout і не submodule). Це дозволяє `ensureWorktree` не створювати вкладений worktree.
+- Side effects: три `git rev-parse` через переданий `run`.
+
+### `ensureWorktree(rest, deps = {})`
+
+- Сигнатура: `(rest: string[], deps?) => { code: number, worktreeDir?: string, branch?: string, desc?: string, baseCommit?: string | null }`.
+- Параметри:
+  - `rest` — `[branch, ...descWords]`. Опис склеюється пробілом, `trim`-иться.
+  - `deps.run` — runner (default `realRun`).
+  - `deps.cwd` — стартовий каталог (default `process.cwd()`).
+  - `deps.log` — функція логування (default `console.error`).
+- Поведінка:
+  1. Якщо `branch` або `desc` порожні — логує usage і повертає `{ code: 1 }`.
+  2. Якщо вже в linked worktree — використовує поточний `cwd` як `worktreeDir`, логує підказку.
+  3. Інакше — викликає `npx @nitra/cursor worktree add <branch> <desc>`; на помилку повертає `{ code: 1 }` із поясненням зі `stderr`.
+  4. Дізнається `HEAD` у `worktreeDir`. Якщо `git rev-parse HEAD` успішний — це `baseCommit`, інакше `null`.
+- Side effects: можливе створення worktree через зовнішній CLI, git-виклики.
+
+### `init(rest, deps = {})`
+
+- Сигнатура: `(rest: string[], deps?) => Promise<number>`.
+- Параметри:
+  - `rest` — `[branch, ...descWords]`.
+  - `deps.now` — джерело часу (default `Date.now`); решта успадковуються `ensureWorktree`.
+- Кроки:
+  1. Делегує `ensureWorktree`; ранній exit при `code !== 0`.
+  2. Шлях стану: `flowStatePath(worktreeDir)` (з `state-store.mjs`).
+  3. Визначає `level` та `risk` через `detectLevel(desc)` / `detectRisk(desc)` (з `level.mjs`).
+  4. Через `writeState` записує початковий запис: `branch`, `status: 'in_progress'`, `started_at` (ISO від `now()`), `metadata.base_commit`, `level`, `risk`, порожній `plan: []`.
+  5. Логує підсумок і повертає `0`.
+- Side effects: створення/перезапис `.flow.json`.
+
+### `verify(_rest, deps = {})`
+
+- Сигнатура: `(_rest: string[], deps?) => Promise<number>`. `_rest` не використовується.
+- Параметри `deps`:
+  - `run`, `cwd`, `log` (стандартні).
+  - `branch` — опціональний явний фільтр для резолва активного flow.
+  - `fingerprint` — фабрика fingerprint-функції; default — `worktreeFingerprint` із `cwd`-залежним sync-runner-ом.
+- Кроки:
+  1. `resolveActiveFlowState({ cwd, branch }, deps)` — cwd-незалежний пошук активного `.flow.json`. Якщо знайшли autoResolved — логує лейбл.
+  2. Якщо `branch` явно задано і не резолвиться — це помилка наміру: повертає `1` із поясненням (інакше `flow verify --branch typo` міг би «зеленіти» в CI).
+  3. Робочий `cwd` для gate-ів: `resolved.worktreeDir ?? cwd0`.
+  4. Читає стан; якщо нема (відсутній/пошкоджений `.flow.json`) — verify лишається толерантним: гейти прогоняються standalone, без запису стану. Логує warn із описом причини.
+  5. Якщо стан є, але `plan` порожній — лише warning (м'які ворота).
+  6. Викликає `runReview({ run, cwd, fingerprint })` (з `reviewer.mjs`). Отримує `{ pass, gates, fingerprint, failedOutput }`.
+  7. Для кожного gate логує `✅`/`❌`. На фейл — `failedOutput`.
+  8. Якщо стан був — `recordTransition` записує подію `{ type: 'verify', pass }` і оновлює `gates`, `fingerprint`, `status` (`failed` при провалі, інакше зберігає попередній).
+  9. Повертає `0` / `1` залежно від `verdict.pass`.
+- Side effects: gate-команди (lint/test/тощо) у `cwd`, лог-вивід, можливі `.flow.json` + події.
+
+### `matchChangedWorkspaces(subWorkspaces, changedFiles)`
+
+- Сигнатура: `(subWorkspaces: string[], changedFiles: string[]) => string[]`.
+- Параметри:
+  - `subWorkspaces` — теки воркспейсів **без** кореня (`.`).
+  - `changedFiles` — змінені шляхи відносно кореня репозиторію у posix-форматі.
+- Логіка: сортує воркспейси за довжиною (спадно), для кожного зміненого файла знаходить **найглибший** збіг (`f === w || f.startsWith(w + '/')`). Таке правило усуває хибне `«кілька воркспейсів»` для випадку, коли `apps` і `apps/web` обидва зареєстровані, а файл `apps/web/x` має належати лише найглибшому.
+- Повертає підмножину `subWorkspaces` (у вхідному порядку), які отримали хоч один хіт.
+- Side effects: немає (чиста функція).
+
+### `resolveChangeWsArgs({ rest, baseCommit, cwd, listWorkspaces, changedFilesSince, log })` (внутрішня)
+
+- Сигнатура: `(input) => Promise<{ args: string[], error?: boolean }>`.
+- Призначення: добудовує `--ws <шлях>` до аргументів `change`, якщо користувач не задав явно.
+- Кроки:
+  1. Якщо `rest` уже містить `--ws` або `--ws=...` — повертає `rest` без змін (поважає явний намір).
+  2. `listWorkspaces(cwd)` → масив. Відсіює корінь (`.`); якщо subworkspace-ів нема — `change` дефолтиться на `.`, лишаємо як є.
+  3. `hits = matchChangedWorkspaces(subWs, changedFilesSince(baseCommit, cwd))`.
+  4. `hits.length > 1` → fail-hard: `{ args: rest, error: true }`, лог із переліком.
+  5. `hits.length === 1` → додає `--ws <hits[0]>` і логує інференс.
+  6. `hits.length === 0` → лишає `rest`.
+  7. У будь-якому виключенні від `listWorkspaces` / `changedFilesSince` — fail-soft: лог warning, повертає `rest`.
+- Side effects: `git diff`-подібні виклики через `changedFilesSince`, виклик `listWorkspaces`, логування.
+
+### `release(rest, deps = {})`
+
+- Сигнатура: `(rest: string[], deps?) => Promise<number>`.
+- Параметри `deps`:
+  - `run`, `cwd`, `log`, `now` — стандартні.
+  - `branch` — опціональний фільтр активного flow.
+  - `listWorkspaces` — default `getMonorepoProjectRootDirs` (з `rules/changelog/lib/package-manifest.mjs`).
+  - `changedFilesSince` — default `collectChangedFilesSince`.
+- Кроки:
+  1. `resolveActiveFlowState({ cwd, branch }, deps)`. Якщо `statePath` не знайдено — `release` падає (`code 1`) із поясненням (це обов'язкова прив'язка).
+  2. `effectiveCwd = resolved.worktreeDir ?? cwd`.
+  3. `readState(statePath)`. Якщо стану нема — `release: стану нема — спершу 'flow init'`, `1`.
+  4. Якщо `state.gate?.verdict === 'FAIL'` — лише warning (м'які ворота, рішення за людиною).
+  5. `resolveChangeWsArgs(...)`. Якщо повернув `error: true` (кілька воркспейсів) — exit `1`.
+  6. Викликає `npx @nitra/cursor change <args>` у `effectiveCwd`. Помилка → exit `1` із поясненням зі stderr.
+  7. `buildCompletionSnapshot({ ...state, status: 'done' }, now)` — снапшот завершення.
+  8. `recordTransition` записує подію `{ type: 'release' }`, оновлює стан: `status: 'done'`, `completion: snapshot`.
+  9. Якщо в стані вказано `state.task` (шлях task-record) — пише summary у task через `writeSummaryToTaskRecord` (з абсолютизацією через `join(effectiveCwd, …)`, якщо шлях відносний).
+  10. Логує `release: done`, повертає `0`.
+- Side effects: `npx … change`, запис у `.flow.json`, можливий запис у task-record, події.
+
+## Залежності
+
+### Імпорти Node-стандарту
+
+- `node:child_process` → `spawnSync` (для `realRun` і дефолтного `fingerprint`).
+- `node:path` → `isAbsolute`, `join` (для шляху task-record у `release`).
+- `node:process` → `cwd as processCwd` (default `cwd`).
+
+### Внутрішні модулі проєкту
+
+- `../../lib/worktree.mjs` → `worktreePaths` — резолв шляху checkout після `worktree add`.
+- `../../lib/changed-files.mjs` → `collectChangedFilesSince` — default для `changedFilesSince` у `release`.
+- `../../utils/worktree-fingerprint.mjs` → `worktreeFingerprint` — default для `verify`.
+- `../../../rules/changelog/lib/package-manifest.mjs` → `getMonorepoProjectRootDirs` — default для `listWorkspaces`.
+- `./events.mjs` → `flowEventsPath` — шлях файла подій flow.
+- `./level.mjs` → `detectLevel`, `detectRisk` — класифікація задачі на основі опису.
+- `./reviewer.mjs` → `runReview` — Quality Gates («Суддя»).
+- `./snapshot.mjs` → `buildCompletionSnapshot`, `writeSummaryToTaskRecord` — completion-снапшот для `release`.
+- `./state-store.mjs` → `flowStatePath`, `readState`, `recordTransition`, `writeState` — персистенція `.flow.json` + події.
+- `./flow-resolve.mjs` → `resolveActiveFlowState` — cwd-незалежний резолв активного flow.
+
+### Зовнішні CLI (через `run`)
+
+- `npx @nitra/cursor worktree add <branch> <desc>` — створення worktree (`ensureWorktree`).
+- `npx @nitra/cursor change <args>` — генерація `.changes` (`release`).
+- `git rev-parse --git-dir|--git-common-dir|--show-superproject-working-tree|HEAD` — детекція worktree та base-коміт.
+
+## Потік виконання / Використання
+
+### Типовий happy-path Ф2
+
+1. `n-cursor flow init feature/x "опис задачі"` → `init`:
+   - `ensureWorktree` створює (або підхоплює) worktree.
+   - `detectLevel` / `detectRisk` класифікують задачу.
+   - Створюється `.flow.json` зі `status: 'in_progress'`, фіксується `base_commit`.
+2. Робота над кодом всередині worktree.
+3. `n-cursor flow verify` → `verify`:
+   - Резолвиться активний flow (cwd-незалежно).
+   - `runReview` прогоняє gate-и (lint, тести, тощо).
+   - Стан оновлюється: `gates`, `fingerprint`. На фейл — `status: 'failed'`.
+4. `n-cursor flow release --bump minor --section feat --message "…"` → `release`:
+   - Резолв активного flow (обов'язковий).
+   - Інференс `--ws` із diff від `base_commit` (якщо не задано явно).
+   - `npx @nitra/cursor change …` пише `.changes`.
+   - `buildCompletionSnapshot` + `recordTransition` фіксують `status: 'done'`.
+   - Якщо є `state.task` — summary йде у task-record.
+
+### Точки розширення (через `deps`)
+
+- Юніт-тести підставляють фейкові `run`, `log`, `now`, `fingerprint`, `listWorkspaces`, `changedFilesSince`, `branch`, `cwd`.
+- Це дозволяє покрити edge-кейси: відсутній стан, кілька воркспейсів у diff, помилки `npx`, артефакти `git rev-parse`.
+
+### Контракти CLI
+
+- `init` / `release` потребують `<branch> "<опис>"` (init) та активного flow + опційних `--bump|--section|--message|--ws` (release).
+- `verify` — без обов'язкових аргументів; толерантний до відсутності стану (запуск standalone у поточному `cwd`).
+- `--branch <name>` як `deps.branch` дозволяє адресувати конкретний flow (CI/довільний `cwd`).
+
+### Інваріанти
+
+- Усі handler-и **не змінюють код** проєкту (`verify` read-only, `release` лише пише `.changes` / `.flow.json` / task-summary).
+- Worktree-вкладеність заборонена: `ensureWorktree` детектить, що `cwd` уже linked worktree, і повторно `worktree add` не викликає.
+- М'які ворота: і відсутність `plan`, і `gate.verdict === 'FAIL'` дають лише warning, рішення про реліз — за людиною.
+- Fail-hard у `release`: відсутність активного flow та неоднозначний воркспейс (multi-hit `matchChangedWorkspaces`).
+
+## Rebuild Test
+
+Маючи цю документацію, інженер може відтворити публічний контракт модуля без читання вихідного коду:
+
+- Знає список і сигнатури експортованих функцій (`realRun`, `ensureWorktree`, `init`, `verify`, `matchChangedWorkspaces`, `release`) та їхні exit code.
+- Розуміє роль `deps` як набору ін'єкцій (`run`, `cwd`, `log`, `now`, `fingerprint`, `branch`, `listWorkspaces`, `changedFilesSince`).
+- Може повторити доменну поведінку: детекцію linked worktree, інференс `--ws` (single/multi/empty/explicit), толерантність `verify` до відсутнього стану, fail-hard `release`, м'які ворота на `plan`/`gate.verdict`.
+- Знає форму `.flow.json` (поля `branch`, `status`, `started_at`, `metadata.base_commit`, `level`, `risk`, `plan`, `gates`, `fingerprint`, `completion`, `task`) і які підкоманди їх записують.
+- Бачить зовнішні CLI/git-залежності та внутрішні модулі, від яких залежить логіка.
+- Розуміє, які підкоманди (`run`/`resume`/`cancel`/`repair`) ще не реалізовані тут (Ф4).