@nitra/cursor 3.22.0 → 3.23.0

package/scripts/dispatcher/docs/graph.md

@@ -0,0 +1,346 @@
+# graph.mjs — DAG-позиція вузлів графа (`n-cursor graph`)
+
+## Огляд
+
+Модуль реалізує **read-only** підкоманду `n-cursor graph` — інспекцію поточного стану DAG-графа задач, описаного контрактом `docs/specs/2026-06-01-node-dag-state.md`. У цьому файлі реалізовано **перший зріз** — `status`: сканування каталогу `docs/graphs/<graph>/nodes/`, групування артефактів-файлів по вузлах, деривацію статусу кожного вузла та текстове відображення позиції графа.
+
+Ключові архітектурні рішення:
+
+- **State-on-FS**: ввесь стан DAG зберігається у markdown-файлах у `docs/graphs/<graph>/nodes/`. Модуль нічого не мутує — лише читає.
+- **Pure derivation**: статус вузла обчислюється з набору файлів-артефактів та їх front-matter, без зовнішніх БД/сервісів.
+- **DI for FS**: усі функції приймають інжектовані `readdir` / `readFile` через об'єкт `deps`, що робить логіку детермінованою та тестованою без доступу до файлової системи.
+- **Stem + qid модель**: ім'я файлу-артефакта складається з `<stem><суфікс>.md`, де `<stem>` — `id-slug` вузла (наприклад, `B02-parser`), а суфікс позначає тип артефакту (`.plan`, `.claim`, `.fact`, `.ask-<qid>`, `.ans-<qid>`).
+- **Roadmap**: подальші зрізи — `claim`, `tick`, `dispatch` — у цьому файлі ще не реалізовані; згадані лише як plan-маркери в JSDoc-заголовку.
+
+Категорії статусів вузла (значення поля `status`): `done`, `failed`, `awaiting-human`, `in_progress`, `ready`, `blocked`.
+
+## Експорти / API
+
+| Експорт                         | Тип            | Призначення                                                                          |
+| ------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
+| `classifyArtifact(name)`        | named function | Класифікує ім'я файлу-артефакту в `{ stem, kind, qid? }`.                            |
+| `parseIdList(value)`            | named function | Парсить inline-список `[A, B]` із front-matter у масив id.                           |
+| `scanGraph(root, graph, deps?)` | named function | Сканує `docs/graphs/<graph>/nodes/`, групує артефакти, повертає сирий список вузлів. |
+| `deriveStatus(node, doneSet)`   | named function | Чисте обчислення статусу одного вузла на базі прапорців та `dependsOn`.              |
+| `deriveGraph(nodes)`            | named function | Деривує статус для всіх вузлів графа (спочатку обчислюючи `doneSet`).                |
+| `renderGraph(graph, nodes)`     | named function | Текстовий рендер графа в одну багаторядкову таблицю.                                 |
+| `runGraphCli(args, deps?)`      | named function | CLI-точка входу для `n-cursor graph <sub> [graph]`.                                  |
+
+Внутрішня (не експортована):
+
+- `listGraphs(root, readdir)` — перелік підкаталогів у `docs/graphs/`.
+
+Константи (модульно-приватні):
+
+- `PLAIN` — масив пар `[суфікс, kind]` для артефактів без `qid`:
+  - `.plan` → `plan`
+  - `.claim` → `claim`
+  - `.fact` → `fact`
+- `QID` — масив пар `[префікс, kind]` для артефактів з `qid`:
+  - `.ask-` → `ask`
+  - `.ans-` → `ans`
+
+## Функції
+
+### `classifyArtifact(name)`
+
+**Сигнатура:** `(name: string) => { stem: string, kind: string, qid?: string } | null`
+
+**Параметри:**
+
+- `name` — рядок з іменем файлу (очікується закінчення на `.md`).
+
+**Повертає:** об'єкт класифікації або `null`, якщо файл не схожий на артефакт.
+
+**Алгоритм:**
+
+1. Якщо ім'я не закінчується на `.md` — повертається `null`.
+2. Відрізається суфікс `.md` → `base`.
+3. Перебираються пари в `PLAIN`; перший суфікс, на який закінчується `base`, дає `{ stem: base без суфікса, kind }`.
+4. Якщо PLAIN не спрацював — перебираються пари в `QID`. Для кожної шукається **остання** входженість префікса (`lastIndexOf`), і якщо знайдено, повертається `{ stem: base до префікса, kind, qid: усе після префікса }`.
+5. Якщо нічого не підійшло — `null`.
+
+**Side effects:** немає (чиста функція).
+
+**Приклади:**
+
+- `classifyArtifact('B02-parser.plan.md')` → `{ stem: 'B02-parser', kind: 'plan' }`
+- `classifyArtifact('B02-parser.ask-q1.md')` → `{ stem: 'B02-parser', kind: 'ask', qid: 'q1' }`
+- `classifyArtifact('README.md')` → `null`
+
+---
+
+### `parseIdList(value)`
+
+**Сигнатура:** `(value: string | null | undefined) => string[]`
+
+**Параметри:**
+
+- `value` — значення поля front-matter, наприклад `"[A, B, C]"`.
+
+**Повертає:** масив id; порожні елементи відкидаються; усі елементи `trim`-аються.
+
+**Алгоритм:** якщо `value` не рядок — повертається `[]`; інакше прибираються перший `[` та перший `]`, рядок ділиться по комі, кожен елемент trim-ається, відфільтровуються falsy значення.
+
+**Side effects:** немає.
+
+**Зауваги:**
+
+- `replace('[', '')` / `replace(']', '')` без `g`-флага: видаляється лише перше входження кожної дужки — інші лишаються в результаті.
+
+---
+
+### `scanGraph(root, graph, deps?)`
+
+**Сигнатура:** `(root: string, graph: string, deps?: { readdir?, readFile? }) => Node[]`
+
+**Параметри:**
+
+- `root` — абсолютний шлях до кореня репо.
+- `graph` — id графа (= ім'я каталогу під `docs/graphs/`).
+- `deps.readdir` — функція `(dir: string) => string[]`; за замовчуванням обгортка над `fs.existsSync` + `fs.readdirSync` (повертає `[]`, якщо каталога немає).
+- `deps.readFile` — функція `(file: string) => string`; за замовчуванням `fs.readFileSync(file, 'utf8')`.
+
+**Повертає:** масив об'єктів-вузлів. Кожен вузол має поля:
+
+| Поле         | Тип              | Значення                                                        |
+| ------------ | ---------------- | --------------------------------------------------------------- |
+| `stem`       | `string`         | `id-slug` стем артефакту                                        |
+| `id`         | `string`         | id вузла (із front-matter `plan` або `stem.split('-')[0]`)      |
+| `slug`       | `string`         | усе після першого `-` у `stem`                                  |
+| `dependsOn`  | `string[]`       | id-залежності з `plan.dependsOn`                                |
+| `owner`      | `string \| null` | власник з `plan.owner`                                          |
+| `hasClaim`   | `boolean`        | чи присутній `.claim`-артефакт                                  |
+| `hasFact`    | `boolean`        | чи присутній `.fact`-артефакт                                   |
+| `factStatus` | `string \| null` | значення `status` із front-matter `.fact` (за замовч. `'done'`) |
+| `asks`       | `string[]`       | список `qid` з `.ask-<qid>.md` файлів                           |
+| `answered`   | `string[]`       | список `qid` з `.ans-<qid>.md` файлів                           |
+
+**Алгоритм:**
+
+1. Збирається шлях `dir = root/docs/graphs/<graph>/nodes`.
+2. Створюється `Map<stem, node>` та лінива функція `ensure(stem)`, яка ініціалізує запис при першому зверненні.
+3. Для кожного імені у `readdir(dir)`:
+   - класифікується через `classifyArtifact`; якщо `null` — пропускається;
+   - дістається запис вузла за `stem` через `ensure`;
+   - `kind` диспатчиться:
+     - `plan` — читається файл, парситься front-matter, переписуються `id`, `dependsOn`, `owner`;
+     - `claim` — встановлюється `hasClaim = true`;
+     - `fact` — `hasFact = true`, `factStatus` із front-matter або `'done'`;
+     - `ask` — `qid` додається в `asks`;
+     - `ans` — `qid` додається в `answered`.
+4. Повертається `[...byStem.values()]`.
+
+**Side effects:**
+
+- Дефолтні `readdir`/`readFile` читають з реальної ФС.
+- При інжектованих `deps` функція повністю детермінована.
+
+**Зауваги щодо стійкості:**
+
+- `parseFrontMatter` може повернути `null` — fallback `?? {}` гарантує безпечний доступ до полів.
+- Якщо в одному графі є кілька `.plan` файлів для одного `stem`, перемагає останній.
+
+---
+
+### `deriveStatus(node, doneSet)`
+
+**Сигнатура:** `(node, doneSet: Set<string>) => 'done' | 'failed' | 'awaiting-human' | 'in_progress' | 'ready' | 'blocked'`
+
+**Параметри:**
+
+- `node` — об'єкт вузла з полями `hasFact`, `factStatus`, `hasClaim`, `asks`, `answered`, `dependsOn`.
+- `doneSet` — множина `id` вузлів, які вже мають `fact` зі статусом ≠ `'failed'`.
+
+**Повертає:** статус вузла. Логіка пріоритетів (зверху-вниз):
+
+1. `hasFact === true` → якщо `factStatus === 'failed'` → `'failed'`, інакше `'done'`.
+2. Інакше шукається відкрите питання: `openAsk = node.asks.some(q => !node.answered.includes(q))`.
+3. `hasClaim && openAsk` → `'awaiting-human'` (роботу взяли, але потрібна відповідь людини).
+4. `hasClaim` → `'in_progress'`.
+5. Усі `dependsOn` є в `doneSet` → `'ready'`.
+6. Інакше → `'blocked'`.
+
+**Side effects:** немає (чиста функція).
+
+---
+
+### `deriveGraph(nodes)`
+
+**Сигнатура:** `(nodes: Node[]) => (Node & { status })[]`
+
+**Параметри:**
+
+- `nodes` — масив вузлів від `scanGraph`.
+
+**Повертає:** новий масив вузлів з доданим полем `status`.
+
+**Алгоритм:**
+
+1. `doneSet` = множина `id` усіх вузлів, у яких `hasFact && factStatus !== 'failed'`.
+2. Кожен вузол мапиться в `{ ...n, status: deriveStatus(n, doneSet) }`.
+
+**Side effects:** немає.
+
+---
+
+### `renderGraph(graph, nodes)`
+
+**Сигнатура:** `(graph: string, nodes: Node[]) => string`
+
+**Параметри:**
+
+- `graph` — id графа (для заголовка).
+- `nodes` — вузли з полем `status` (тобто результат `deriveGraph`).
+
+**Повертає:** багаторядковий текстовий рендер.
+
+**Формат виводу:**
+
+```
+граф <graph> — <status1>:<n1> <status2>:<n2> ...
+  <id> · <slug> [<status>][ <owner>][ ←[dep1,dep2]]
+  ...
+```
+
+- Якщо `nodes.length === 0` → `"граф <graph>: вузлів не знайдено"`.
+- Заголовок міститиме лише ті статуси, для яких `count > 0`, в порядку `['in_progress', 'awaiting-human', 'ready', 'blocked', 'failed', 'done']`.
+- Для кожного вузла: `id · slug [status]`, потім опційно ` <owner>` (якщо є), потім опційно ` ←[deps]` (якщо є залежності).
+
+**Side effects:** немає.
+
+---
+
+### `listGraphs(root, readdir)` (internal)
+
+**Сигнатура:** `(root: string, readdir: (dir: string) => string[]) => string[]`
+
+Повертає список імен з `docs/graphs/`. Інжектована `readdir` дозволяє підставити dummy-FS. Експортовано не для зовнішнього вжитку — лише як локальний helper.
+
+---
+
+### `runGraphCli(args, deps?)`
+
+**Сигнатура:** `(args: string[], deps?: { cwd?, readdir?, readFile?, log? }) => number`
+
+**Параметри:**
+
+- `args` — позиційні аргументи після слова `graph` у вихідному `argv` (тобто `[sub, graphArg]`).
+- `deps.cwd` — root репо; за замовч. `process.cwd()`.
+- `deps.readdir` — як у `scanGraph`/`listGraphs`.
+- `deps.readFile` — як у `scanGraph`.
+- `deps.log` — функція логування; за замовч. `console.log`.
+
+**Повертає:** exit-код (`0` — все ok, `1` — невідома/відсутня підкоманда).
+
+**Алгоритм:**
+
+1. `root = deps.cwd ?? process.cwd()`.
+2. `[sub, graphArg] = args`.
+3. Якщо `sub !== 'status'` → друкується usage-рядок `Usage: n-cursor graph status [<graph>]` і повертається `1`.
+4. Інакше:
+   - якщо `graphArg` заданий → `graphs = [graphArg]`, інакше — усі підкаталоги `docs/graphs/`.
+   - Якщо `graphs.length === 0` → `"graph: у docs/graphs/ немає графів"` і `0`.
+   - Інакше для кожного `g` друкується `renderGraph(g, deriveGraph(scanGraph(root, g, { readdir, readFile })))`.
+5. Повертається `0`.
+
+**Side effects:**
+
+- Викликає `log` (зазвичай `console.log`).
+- Читає каталог `docs/graphs/` та файли вузлів через дефолтні `readdir`/`readFile`.
+- Не пише в ФС.
+
+## Залежності
+
+### Імпорти з `node:` (стандартна бібліотека Node.js)
+
+- `node:fs` — `existsSync`, `readdirSync`, `readFileSync`. Використовуються лише як дефолти для `deps.readdir`/`deps.readFile`.
+- `node:path` — `join` для побудови шляхів `docs/graphs/<g>/nodes/<file>`.
+- `node:process` — `cwd as processCwd` для дефолту `root`.
+
+### Імпорти з проєкту
+
+- `./trace.mjs` — функція `parseFrontMatter(text)` для парсингу YAML-frontmatter у markdown-файлах артефактів.
+
+### Зовнішні залежності
+
+Немає (npm-залежності не використовуються).
+
+### Контракт і пов'язані документи
+
+- `docs/specs/2026-06-01-node-dag-state.md` — контракт стану DAG-вузлів (форма артефактів і деривація статусу).
+- Структура каталогів: `docs/graphs/<graph>/nodes/<stem><suffix>.md`.
+
+## Потік виконання / Використання
+
+### CLI-сценарій
+
+Файл імпортується диспатчером верхнього рівня (`n-cursor`) і викликається через `runGraphCli`. Очікувана форма виклику з shell:
+
+```
+n-cursor graph status              # усі графи в docs/graphs/
+n-cursor graph status <graph>      # лише один граф
+n-cursor graph                     # друк usage, exit 1
+n-cursor graph <other>             # друк usage, exit 1
+```
+
+### Внутрішня pipeline за один граф
+
+```
+readdir(docs/graphs/<g>/nodes)
+  → for each file: classifyArtifact + readFile (для plan/fact)
+  → scanGraph → Node[]
+  → deriveGraph → Node[] із полем status
+  → renderGraph → string
+  → log(string)
+```
+
+### Програмне використання (наприклад, у тестах)
+
+```js
+import { runGraphCli, scanGraph, deriveGraph, renderGraph } from './graph.mjs'
+
+const logs = []
+const fakeReaddir = dir => {
+  if (dir.endsWith('docs/graphs')) return ['g1']
+  if (dir.endsWith('docs/graphs/g1/nodes'))
+    return ['B01-init.plan.md', 'B01-init.fact.md', 'B02-parser.plan.md', 'B02-parser.claim.md', 'B02-parser.ask-q1.md']
+  return []
+}
+const fakeReadFile = file => {
+  if (file.endsWith('B01-init.plan.md')) return '---\nid: B01\ndependsOn: []\nowner: alice\n---\n'
+  if (file.endsWith('B01-init.fact.md')) return '---\nstatus: done\n---\n'
+  if (file.endsWith('B02-parser.plan.md')) return '---\nid: B02\ndependsOn: [B01]\nowner: bob\n---\n'
+  return ''
+}
+
+const code = runGraphCli(['status'], {
+  cwd: '/repo',
+  readdir: fakeReaddir,
+  readFile: fakeReadFile,
+  log: m => logs.push(m)
+})
+// code === 0
+// logs[0] починається з "граф g1 — awaiting-human:1 done:1"
+```
+
+### Розширення (планується контрактом)
+
+Наступні зрізи DAG (поза цим файлом):
+
+- `claim` — позначення взяття вузла в роботу.
+- `tick` — інкрементальне оновлення стану.
+- `dispatch` — диспатч готових (`ready`) вузлів виконавцям.
+
+### Тестованість
+
+- Усі чисті функції (`classifyArtifact`, `parseIdList`, `deriveStatus`, `deriveGraph`, `renderGraph`) — без I/O, тестуються прямо.
+- `scanGraph`, `runGraphCli`, `listGraphs` — отримують `readdir`/`readFile`/`log` через `deps`, що дозволяє повний unit-тест без диска.
+
+### Граничні випадки
+
+- Каталог `docs/graphs/<g>/nodes` відсутній → дефолтний `readdir` повертає `[]` → `scanGraph` віддає порожній масив → `renderGraph` друкує `"граф <g>: вузлів не знайдено"`.
+- Файл без розпізнаного суфікса → пропускається.
+- `parseFrontMatter` повертає `null` → fallback `?? {}` запобігає винятку.
+- Кілька `plan`/`fact` для одного `stem` → перемагає останній проскансований; `claim`/`ask`/`ans` — кумулятивні.
+- `parseIdList` із вкладеними дужками (наприклад `"[[A], B]"`) — `replace` без флага `g` видалить лише першу пару, інші лишаться у значеннях.

package/scripts/dispatcher/docs/index.md

@@ -0,0 +1,236 @@
+# `npm/scripts/dispatcher/index.mjs`
+
+## Огляд
+
+Файл реалізує **CLI-диспетчер підкоманди `n-cursor flow`** — точку входу другого рівня, до якої делегує гілка `case 'flow'` у `bin/n-cursor.js`. Реалізація відповідає специфікації §8 "Dual-Mode Dispatcher" і надає два фасади поверх єдиного джерела істини `.flow.json`:
+
+- **Фасад A — "Пасивний Турнікет"** (`init`, `spec`, `plan`, `verify`, `review`, `gate`, `release`). Призначений для IDE-агентів (Cursor, Claude Code), які самі пишуть код; `n-cursor` лише виносить вердикт (judge).
+- **Фасад B — "Активний Раннер"** (`run`, `resume`, `cancel`, `repair`). Повний 5-фазний polyfill-цикл для headless/CI-сценаріїв, де агент відсутній.
+
+Модуль не містить ні I/O-побічних ефектів сам по собі (окрім `console.error` для usage), ні бізнес-логіки фаз. Він виключно:
+
+1. парсить `argv` (підкоманда + опційний прапорець `--branch <гілка>`);
+2. валідовує наявність handler-а;
+3. делегує виклик до конкретного handler-модуля з директорії `./lib/`;
+4. повертає `exit code` (число).
+
+Така архітектура дає змогу повністю мокати `handlers` через DI в тестах, а сам диспатчер тримати тонким і детермінованим.
+
+## Експорти / API
+
+Модуль ESM (`.mjs`). Експортує:
+
+| Експорт             | Тип                                                                          | Призначення                                                                                                                                       |
+| ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DEFAULT_HANDLERS`  | `Record<string, (rest: string[], deps: object) => Promise<number>>`          | Стандартна мапа підкоманд → handler-функцій (`init`, `spec`, `plan`, `verify`, `review`, `gate`, `release`, `run`, `resume`, `cancel`, `repair`). |
+| `extractBranchFlag` | `function(args: string[]) → { rest: string[], branch: string \| undefined }` | Чистий парсер опційного `--branch <гілка>` / `--branch=<гілка>`; повертає очищений масив аргументів і значення гілки (або `undefined`).           |
+| `runFlowCli`        | `async function(args: string[], deps?: object) → Promise<number>`            | Власне точка входу диспатчера; маршрутизує підкоманду на handler і повертає exit code.                                                            |
+
+Default-експорту немає — імпорт іменований.
+
+## Функції
+
+### `extractBranchFlag(args)`
+
+**Сигнатура.**
+
+```js
+export function extractBranchFlag(args: string[]): { rest: string[], branch: string | undefined }
+```
+
+**Параметри.**
+
+- `args: string[]` — масив "сирих" аргументів, які залишилися після виокремлення підкоманди (тобто `argv` без префіксу `flow <sub>`).
+
+**Повертає.**
+
+Об'єкт із двома полями:
+
+- `rest: string[]` — очищений масив аргументів, з якого вилучено всі форми `--branch …`.
+- `branch: string | undefined` — значення гілки, якщо було вказано непорожньою формою; інакше `undefined`.
+
+**Підтримувані форми прапорця.**
+
+- Пробільна форма: `--branch <гілка>` — поглинає **наступний** аргумент **лише** якщо він існує і не починається з `-` (щоб не "з'їсти" сусідній прапорець); інакше `--branch` тихо стає no-op без помилки.
+- Inline-форма: `--branch=<гілка>` — значення береться суфіксом після `=`. Порожній суфікс (`--branch=`) ігнорується (гілку не встановлює).
+
+**Особливості / захисти.**
+
+- Захист від тихого "пожирання" сусіднього прапорця: `--branch --other-flag` не призведе до того, що `--other-flag` стане значенням гілки.
+- Може зустрічатися кілька разів — **остання** валідна форма перемагає (стандартна семантика циклу: змінна `branch` перезаписується).
+- Чиста функція: не залежить від `process`, файлової системи чи мережі.
+
+**Side effects.** Жодних.
+
+---
+
+### `runFlowCli(args, deps)`
+
+**Сигнатура.**
+
+```js
+export async function runFlowCli(
+  args: string[],
+  deps?: {
+    handlers?: Record<string, (rest: string[], deps: object) => Promise<number>>,
+    branch?: string,
+    // …довільні інші deps, які потрібні конкретним handler-ам (логер, fs-мок тощо)
+  }
+): Promise<number>
+```
+
+**Параметри.**
+
+- `args: string[]` — масив аргументів **після** слова `flow`. Перший елемент трактується як підкоманда (`sub`), решта — як її аргументи (`raw`).
+- `deps` — опційний об'єкт ін'єкції залежностей:
+  - `deps.handlers` — кастомна мапа handler-ів (для тестів / альтернативних збірок). Якщо не передано, використовується `DEFAULT_HANDLERS`.
+  - `deps.branch` — попередньо встановлена гілка з вищого рівня; має пріоритет над тією, що витягнута з `args` (`deps.branch ?? branch`).
+  - Інші довільні поля проходять "прозоро" до handler-а через spread `{ ...deps, branch: … }`.
+
+**Повертає.**
+
+`Promise<number>` — exit code:
+
+- `1` — підкоманда відсутня (`!sub`) або невідома (`Object.hasOwn(handlers, sub) === false`). У цьому разі додатково надсилається текст `USAGE` у `stderr` через `console.error`.
+- Будь-яке інше число — результат, який повернув викликаний handler.
+
+**Side effects.**
+
+- При невалідному вводі — запис у `stderr` (`console.error(USAGE)`).
+- Делегує **всі** інші побічні ефекти (читання `.flow.json`, мутації worktree, git-операції тощо) у handler-модулі — сам диспатчер їх не виконує.
+
+**Алгоритм (по кроках).**
+
+1. Деструктурує `args` як `[sub, ...raw]`.
+2. Бере `handlers = deps.handlers ?? DEFAULT_HANDLERS`.
+3. Перевірка валідності: якщо `sub` фолсі або `Object.hasOwn(handlers, sub)` === `false` → `console.error(USAGE)` і `return 1`. `Object.hasOwn` ужито замість `in`/`hasOwnProperty`, щоб уникнути колізій із prototype-полями (безпечніше для ін'єкційного `handlers`).
+4. Викликає `extractBranchFlag(raw)` → отримує `{ rest, branch }`.
+5. Викликає `await handlers[sub](rest, { ...deps, branch: deps.branch ?? branch })` і повертає його результат.
+6. Передача `branch` далі в `deps` забезпечує cwd-незалежний резолв стану (беклог №1 — `.flow.json` можна знайти й виконати команду поза worktree).
+
+## Залежності
+
+Усі залежності — **локальні** ESM-імпорти з директорії `./lib/`. Кожен handler — окремий модуль; диспатчер не знає їхньої внутрішньої логіки.
+
+| Імпорт                              | З модуля             | Призначення / Фасад                                                                                                                                                                |
+| ----------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cancel`, `repair`, `resume`, `run` | `./lib/active.mjs`   | Фасад B — Активний Раннер: повний 5-фазний цикл (`run`), продовження з чекпойнта (`resume`), скасування з прибиранням стану (`cancel`), відновлення пошкодженого стану (`repair`). |
+| `init`, `release`, `verify`         | `./lib/commands.mjs` | Фасад A — Турнікет: створення worktree + `.flow.json` (`init`), Quality Gates (`verify`), фіксація `.changes` + completion snapshot (`release`).                                   |
+| `gate`                              | `./lib/gate.mjs`     | Фасад A: фінальний вердикт `PASS / CONCERNS / FAIL` (комбінований `verify + review`).                                                                                              |
+| `plan`                              | `./lib/plan.mjs`     | Фасад A: фаза плану → `docs/plans/<…>` + оновлення стану.                                                                                                                          |
+| `review`                            | `./lib/review.mjs`   | Фасад A: adversarial diff-review (інтенсивність залежить від `level`).                                                                                                             |
+| `spec`                              | `./lib/spec.mjs`     | Фасад A: фаза дизайну → `docs/specs/<…>`.                                                                                                                                          |
+
+**Зовнішніх npm-залежностей немає** — модуль використовує лише вбудоване `console` API та `Object.hasOwn` (ECMAScript 2022+).
+
+## Потік виконання / Використання
+
+### Як викликається
+
+Модуль вмонтований у CLI як обробник підкоманди `flow` у `bin/n-cursor.js`. Скорочена картина:
+
+```js
+// у bin/n-cursor.js
+import { runFlowCli } from '../npm/scripts/dispatcher/index.mjs'
+
+switch (cmd) {
+  case 'flow':
+    process.exit(await runFlowCli(rest))
+    break
+  // …інші команди
+}
+```
+
+### Приклади з CLI
+
+Усі приклади з блоку `USAGE`, який видається у `stderr` при невалідному виклику:
+
+```text
+npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json (+ level)
+npx @nitra/cursor flow spec [--panel]     # Фасад A: фаза дизайну → docs/specs/<…>
+npx @nitra/cursor flow plan [--panel]     # Фасад A: фаза плану → docs/plans/<…> + state
+npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)
+npx @nitra/cursor flow review             # Фасад A: adversarial diff-review (за level)
+npx @nitra/cursor flow gate               # Фасад A: вердикт PASS/CONCERNS/FAIL (verify+review)
+npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot
+npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл
+npx @nitra/cursor flow resume             # продовжити з чекпойнта
+npx @nitra/cursor flow cancel             # скасувати, прибрати стан
+npx @nitra/cursor flow repair [--discard-step-work]   # відновлення пошкодженого стану
+```
+
+### Опційний `--branch <гілка>`
+
+Підтримується **для будь-якої** підкоманди. Допомагає, коли користувач запускає `n-cursor flow …` **поза** worktree цільової задачі — гілка вказує, який `.flow.json` (з якого worktree-резолва) брати.
+
+Приклади:
+
+```bash
+npx @nitra/cursor flow verify --branch feature/payments
+npx @nitra/cursor flow verify --branch=feature/payments
+```
+
+### Програмний виклик (для тестів)
+
+`runFlowCli` повністю замокується через DI:
+
+```js
+import { runFlowCli } from './npm/scripts/dispatcher/index.mjs'
+
+const calls = []
+const fakeHandlers = {
+  verify: async (rest, deps) => {
+    calls.push({ rest, deps })
+    return 0
+  }
+}
+
+const code = await runFlowCli(['verify', '--branch', 'main'], { handlers: fakeHandlers })
+// code === 0
+// calls[0].deps.branch === 'main'
+// calls[0].rest === []
+```
+
+### Послідовність кроків `runFlowCli`
+
+1. Деструктуризація `args` → `sub` + `raw`.
+2. Підбір мапи handler-ів (`deps.handlers ?? DEFAULT_HANDLERS`).
+3. Валідація `sub` через `Object.hasOwn(handlers, sub)`.
+   - Якщо невалідно → `console.error(USAGE)` + `return 1`.
+4. Парсинг `--branch` через `extractBranchFlag(raw)` → `{ rest, branch }`.
+5. Виклик `handlers[sub](rest, { ...deps, branch: deps.branch ?? branch })`.
+6. Повернення exit code від handler-а як результату Promise.
+
+### Коди завершення
+
+| Код            | Коли                                                                     | Хто повертає                   |
+| -------------- | ------------------------------------------------------------------------ | ------------------------------ |
+| `1`            | відсутня або невідома підкоманда (`!sub` чи `Object.hasOwn` === `false`) | сам диспатчер                  |
+| будь-яке число | результат handler-а                                                      | відповідний модуль із `./lib/` |
+
+### Обмеження та інваріанти
+
+- Диспатчер **не** інтерпретує жоден аргумент окрім `--branch`; усі інші опції-прапорці (`--panel`, `--discard-step-work` тощо) прокидаються в handler як частина `rest`.
+- Усі handler-и повинні повертати `Promise<number>`; синхронний throw обірве промісі та "вибухне" вище — це навмисно (диспатчер не маскує внутрішні помилки фаз).
+- Кеш стану й бізнес-логіка фаз — поза цим файлом; його роль виключно — маршрутизація.
+
+## Rebuild Test
+
+Якщо реалізацію цього файлу повністю видалити, з опису вище має бути можливо відтворити її без читання оригіналу:
+
+1. ESM-модуль із трьома експортами: `DEFAULT_HANDLERS`, `extractBranchFlag`, `runFlowCli`.
+2. Імпортувати 11 handler-ів із 6 модулів у `./lib/` (`active.mjs` → 4 шт., `commands.mjs` → 3 шт., `gate.mjs`, `plan.mjs`, `review.mjs`, `spec.mjs` → по 1 шт.) і скласти в `DEFAULT_HANDLERS`.
+3. `extractBranchFlag(args)` — лінійний прохід `for`-циклом по `args`:
+   - якщо елемент `=== '--branch'` — спробувати взяти `args[i+1]` як значення, якщо `!== undefined && !startsWith('-')`, інакше залишити `branch` як є; обидва випадки пропускають елемент (не пушать у `rest`); якщо значення взято — `i++` додатково;
+   - інакше якщо елемент `startsWith('--branch=')` — взяти суфікс після `=`, якщо непорожній — присвоїти `branch`; не пушати в `rest`;
+   - інакше — `rest.push(args[i])`.
+   - Повернути `{ rest, branch }`.
+4. `runFlowCli(args, deps = {})`:
+   - `[sub, ...raw] = args`;
+   - `handlers = deps.handlers ?? DEFAULT_HANDLERS`;
+   - якщо `!sub || !Object.hasOwn(handlers, sub)` → `console.error(USAGE); return 1;`
+   - `{ rest, branch } = extractBranchFlag(raw)`;
+   - `return await handlers[sub](rest, { ...deps, branch: deps.branch ?? branch })`.
+5. `USAGE` — багаторядковий текстовий блок із прикладами використання всіх 11 підкоманд + рядок `--branch` у `repair` (опційний `[--discard-step-work]`).
+
+Відтворена реалізація має пройти тести з `npm/scripts/dispatcher/tests/`, які перевіряють: маршрутизацію відомих підкоманд, повернення `1` для невідомих, прокидання `branch` із обох форм прапорця, відмову поглинати сусідній прапорець після `--branch` без значення, ігнорування порожньої форми `--branch=`, пріоритет `deps.branch` над парсингом і DI `handlers` для мок-тестів.