@nitra/cursor 4.1.0 → 4.1.1

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

@@ -1,161 +0,0 @@
-# flow-lock.mjs
-
-## Огляд
-
-Модуль `flow-lock.mjs` надає тонку обгортку над спільною утилітою `withLock` для серіалізації мутацій стану `flow` у межах конкретного git worktree (per-branch). Він не реалізує власної логіки взяття/звільнення лока — натомість **повторно використовує** перевірений механізм `withLock` (spec §4.1.3), який уже коректно:
-
-- чистить stale-локи (TTL + перевірка процесу через `process.kill(pid, 0)`);
-- релізить лок на `SIGINT` / `SIGTERM`;
-- підтримує очікування з poll-інтервалом і таймаутом.
-
-Ключові поведінкові відмінності цього модуля від базового `withLock` (override-и для контексту `flow`):
-
-- **`onWaitTimeout: 'fail'`** — fail-closed. На відміну від lint, де після таймауту прийнятно стартонути «без лока», для `flow` мутацію стану двома writer-ами одночасно не допускається. Якщо лок не вдалось узяти за `waitTimeout` — кидається помилка.
-- **`getFingerprint: () => null`** — dedup за «однаковим деревом» вимкнено. Flow повинен виконатись завжди, а не пропускатись через те, що інший writer щойно мутував той самий стан.
-- **Лок-каталог — sibling до worktree-checkout**: `.flow-lock-<branch>/` створюється поряд із самим worktree-каталогом (`.worktrees/.flow-lock-<branch>/`), а не в глобальному кеш-каталозі ОС. Це усуває залежність від `XDG_CACHE_HOME` / `os.tmpdir()` і прив’язує лок до того ж тому, де живе стан.
-
-Модуль входить у бібліотеку диспетчера (`npm/scripts/dispatcher/lib/`) і є будівельним блоком для усіх кроків, що змінюють persistent-стан `flow` конкретної гілки.
-
-## Експорти / API
-
-Модуль експортує одну іменовану функцію:
-
-| Експорт                                   | Тип        | Призначення                                                                              |
-| ----------------------------------------- | ---------- | ---------------------------------------------------------------------------------------- |
-| `withFlowLock(worktreeDir, runFn, opts?)` | `function` | Виконує `runFn` під per-branch локом flow, прив’язаним до конкретного worktree-каталогу. |
-
-Default export відсутній.
-
-## Функції
-
-### `withFlowLock(worktreeDir, runFn, opts = {})`
-
-Виконує користувацьку асинхронну (або синхронну) функцію `runFn` ексклюзивно для конкретного worktree. Якщо інший процес уже тримає лок, очікує до `opts.waitTimeout`, інакше кидає помилку (fail-closed).
-
-#### Сигнатура
-
-```js
-withFlowLock(worktreeDir: string,
-             runFn: () => unknown | Promise<unknown>,
-             opts?: object): Promise<unknown>
-```
-
-#### Параметри
-
-- `worktreeDir` — `string`, **абсолютний** шлях до checkout-каталогу worktree (наприклад, `/repo/.worktrees/feat-x`). Якщо шлях не абсолютний, функція кидає `Error` (див. нижче).
-- `runFn` — `() => unknown | Promise<unknown>`, критична секція. Викликається без аргументів усередині лока. Може повертати як значення, так і `Promise`.
-- `opts` — `object`, опціональний. Прокидається у `withLock` як є (через spread). Дозволяє переозначити, зокрема:
-  - `waitTimeout` — максимальний час очікування лока (мс);
-  - `pollInterval` — період опитування стану лока (мс);
-  - будь-які інші поля, що підтримує `withLock`.
-
-  **Увага:** опції з override-ів (`onWaitTimeout`, `cacheDir`, `getFingerprint`) **можуть бути перевизначені** користувачем, бо `...opts` стоїть після них у літералі. Якщо потрібно зберегти fail-closed поведінку — не передавайте ці три поля.
-
-#### Повертає
-
-`Promise<unknown>` — те, що повернув `runFn`. Якщо `runFn` кинув помилку — `Promise` відхиляється тією ж помилкою (лок звільнюється у `finally` всередині `withLock`).
-
-#### Винятки
-
-- `Error('withFlowLock: очікується абсолютний шлях (отримано: <worktreeDir>)')` — якщо `worktreeDir` не є абсолютним шляхом (`!isAbsolute(worktreeDir)`).
-- Будь-яка помилка, кинута з `withLock`: зокрема, при `onWaitTimeout: 'fail'` — помилка таймауту очікування лока.
-- Будь-яка помилка, кинута з `runFn` — пробрасується без обгортки.
-
-#### Side effects
-
-- Створює (через `withLock`) каталог `${dirname(worktreeDir)}/.flow-lock-${basename(worktreeDir)}/` для зберігання lock-файлу та допоміжних артефактів (PID, мітки часу — деталі визначає `withLock`).
-- На час виконання `runFn` тримає файловий лок у вищезгаданому каталозі.
-- Реагує на `SIGINT`/`SIGTERM` (через хендлери у `withLock`) — звільняє лок при перериванні процесу.
-- Не виконує жодних мережевих чи git-операцій сам по собі — лише обчислює шляхи та делегує у `withLock`.
-
-#### Логіка обчислення параметрів лока
-
-Усередині функції:
-
-1. `base = basename(worktreeDir)` — ім’я останнього сегменту шляху (наприклад, `feat-x` для `/repo/.worktrees/feat-x`). Використовується як суфікс імені лока та назви кеш-каталогу.
-2. `cacheDir = join(dirname(worktreeDir), `.flow-lock-${base}`)` — каталог, у якому `withLock` зберігає сам lock-файл. Розташовується **поряд** із worktree-каталогом, а не всередині нього (sibling).
-3. Виклик `withLock(name, runFn, options)`:
-   - `name = `flow-${base}`` — стабільний ідентифікатор лока, унікальний у межах гілки.
-   - `options`:
-     - `onWaitTimeout: 'fail'` — fail-closed по таймауту очікування;
-     - `cacheDir` — обчислений вище;
-     - `getFingerprint: () => null` — dedup вимкнено: рівноцінні запуски не «склеюються»;
-     - `...opts` — користувацькі опції зверху (можуть переозначити будь-яке з трьох попередніх полів).
-
-## Залежності
-
-### Зовнішні (Node.js core)
-
-- `node:path` — імпортуються `basename`, `dirname`, `isAbsolute`, `join`. Використовуються для валідації абсолютності шляху та обчислення sibling-каталогу лока і `name` лока.
-
-### Внутрішні (репозиторій)
-
-- `../../utils/with-lock.mjs` (відносно `npm/scripts/dispatcher/lib/flow-lock.mjs` — це `npm/scripts/utils/with-lock.mjs`) — спільна утиліта `withLock`. Відповідає за:
-  - створення lock-файлу;
-  - очищення stale-локів за TTL і `process.kill(pid, 0)`;
-  - обробку `SIGINT`/`SIGTERM`;
-  - polling/wait/timeout логіку;
-  - dedup за fingerprint (тут — вимкнено).
-
-Інших зовнішніх npm-залежностей модуль не має.
-
-## Потік виконання / Використання
-
-### Високорівневий потік виклику
-
-1. Викликач формує абсолютний шлях `worktreeDir` (наприклад, `/repo/.worktrees/feat-x`).
-2. Передає його в `withFlowLock(worktreeDir, runFn, opts?)`.
-3. `withFlowLock`:
-   - валідує, що `worktreeDir` абсолютний (інакше — кидає);
-   - обчислює `base` та `cacheDir`;
-   - делегує у `withLock('flow-<base>', runFn, { onWaitTimeout: 'fail', cacheDir, getFingerprint: () => null, ...opts })`.
-4. `withLock`:
-   - намагається взяти лок у `cacheDir`;
-   - якщо лок зайнятий — чекає до `waitTimeout` з кроком `pollInterval` (значення за замовчуванням — з `withLock`);
-   - якщо за таймаут лок не взято — через `onWaitTimeout: 'fail'` кидає помилку;
-   - якщо взято — виконує `runFn` і у `finally` звільняє лок;
-   - реєструє хендлери `SIGINT`/`SIGTERM`, що звільняють лок при перериванні.
-5. Результат `runFn` повертається через `Promise`.
-
-### Приклад використання
-
-```js
-import { withFlowLock } from './flow-lock.mjs'
-
-const worktreeDir = '/repo/.worktrees/feat-x'
-
-await withFlowLock(
-  worktreeDir,
-  async () => {
-    // Критична секція: мутації стану flow для гілки feat-x
-    await mutateFlowState(worktreeDir)
-  },
-  { waitTimeout: 30_000, pollInterval: 250 }
-)
-```
-
-Поведінка:
-
-- Якщо інший процес уже виконує `withFlowLock` для **того ж самого** `worktreeDir`, поточний виклик чекатиме до 30 с.
-- Якщо за 30 с лок не звільниться — буде кинуто помилку (fail-closed).
-- Для **іншого** `worktreeDir` (інша гілка) лок не блокує — `name` лока містить `basename(worktreeDir)`, тож гілки серіалізуються незалежно.
-
-### Розташування артефактів на диску
-
-Для `worktreeDir = /repo/.worktrees/feat-x`:
-
-- worktree-checkout: `/repo/.worktrees/feat-x/`
-- lock-каталог (sibling): `/repo/.worktrees/.flow-lock-feat-x/`
-
-Sibling-розміщення обрано свідомо, аби:
-
-- не «забруднювати» сам worktree файлом лока (він не є частиною робочого дерева);
-- не залежати від глобального кеш-каталогу ОС (інакше лок-семантика «per-branch у цьому репо» загубилась би на машинах з нестандартним `XDG_CACHE_HOME`).
-
-### Гарантії та обмеження
-
-- **Серіалізація per-branch:** два паралельні виклики `withFlowLock` для одного `worktreeDir` виконуються послідовно.
-- **Незалежність гілок:** виклики для різних `worktreeDir` (різний `basename`) не блокують одне одного.
-- **Fail-closed:** при недоступному локі writer **не** запуститься «оптимістично» — на відміну від lint-сценаріїв.
-- **Без dedup:** навіть якщо викликач передасть свій `getFingerprint`, дефолт `() => null` вимикає «склеювання» однакових запусків; для увімкнення dedup потрібно явно передати `getFingerprint` в `opts` (override `...opts` після дефолтів дозволяє це).
-- **Обов’язковий абсолютний шлях:** відносні шляхи відхиляються одразу — це усуває клас помилок «лок узяли не там, де думали».

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

@@ -1,267 +0,0 @@
-# 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/flow-plan.mjs

@@ -1,153 +0,0 @@
-/**
- * Handler `flow plan` — Stage 1 (думка.MD § "flow plan").
- *
- * Читає `task.md` у поточному вузлі, розбирає `mode` і `hint` з front-matter,
- * знаходить наступний номер `plan_NNN.md`, пише шаблон і виводить контекст для
- * агента (task + mode + hint) на stdout.
- *
- * FS та path-резолвінг ін'єктуються — тестується без реального диска.
- */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { cwd as processCwd } from 'node:process'
-
-const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
-
-/**
- * Парсить YAML front-matter (мінімально: лише прості `key: value` рядки).
- * @param {string} text вміст файлу
- * @returns {Record<string, string>} ключ-значення з front-matter (рядки)
- */
-function parseFrontMatter(text) {
-  const m = text.match(FRONT_MATTER_RE)
-  if (!m) return {}
-  const result = {}
-  for (const line of m[1].split(/\r?\n/)) {
-    const idx = line.indexOf(':')
-    if (idx === -1) continue
-    const key = line.slice(0, idx).trim()
-    const val = line.slice(idx + 1).trim()
-    if (key) result[key] = val
-  }
-  return result
-}
-
-/**
- * Знаходить наступний номер `plan_NNN.md` у директорії вузла.
- * @param {string} dir абсолютний шлях до директорії вузла
- * @param {(dir: string) => string[]} readdir інжектована readdir
- * @returns {string} рядок типу `001`, `002`, …
- */
-function nextPlanNumber(dir, readdir) {
-  const files = readdir(dir)
-  let max = 0
-  for (const f of files) {
-    const m = f.match(/^plan_(\d+)\.md$/)
-    if (m) {
-      const n = parseInt(m[1], 10)
-      if (n > max) max = n
-    }
-  }
-  return String(max + 1).padStart(3, '0')
-}
-
-/**
- * Будує вміст шаблону `plan_NNN.md`.
- * @param {{ mode: string, hint: string, now: string }} params параметри
- * @returns {string} вміст файлу
- */
-export function buildPlanTemplate({ mode, hint, now }) {
-  return [
-    '---',
-    `created_at: ${now}`,
-    `mode: ${mode}`,
-    `decision: ${hint || 'atomic | composite'}`,
-    '---',
-    '',
-    '## Context',
-    "<!-- Чому саме такий підхід — що агент/людина з'ясували -->",
-    '',
-    '## Approach',
-    '<!-- atomic: покроковий план виконання -->',
-    '<!-- composite: список дочірніх вузлів з описами -->',
-    '',
-    '## Risks',
-    '<!-- Що може піти не так -->',
-    ''
-  ].join('\n')
-}
-
-/**
- * `flow plan` handler.
- *
- * @param {string[]} _rest аргументи після `plan` (не використовуються)
- * @param {{
- *   cwd?: string,
- *   log?: (m: string) => void,
- *   readFile?: (path: string, enc: string) => string,
- *   writeFile?: (path: string, content: string, enc: string) => void,
- *   readdir?: (dir: string) => string[],
- *   exists?: (path: string) => boolean,
- *   now?: () => string
- * }} [deps] ін'єкції
- * @returns {Promise<number>} exit code
- */
-export async function plan(_rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
-  const log = deps.log ?? console.error
-  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
-  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
-  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
-  const exists = deps.exists ?? existsSync
-  const nowFn = deps.now ?? (() => new Date().toISOString())
-
-  const taskPath = join(cwd, 'task.md')
-  if (!exists(taskPath)) {
-    log('flow plan: task.md не знайдено в CWD')
-    return 1
-  }
-
-  let taskContent
-  try {
-    taskContent = readFile(taskPath, 'utf8')
-  } catch (err) {
-    log(`flow plan: не вдалося прочитати task.md — ${err instanceof Error ? err.message : String(err)}`)
-    return 1
-  }
-
-  const fm = parseFrontMatter(taskContent)
-  const mode = fm.mode || 'human'
-  const hint = fm.hint || ''
-
-  const num = nextPlanNumber(cwd, readdir)
-  const planPath = join(cwd, `plan_${num}.md`)
-
-  const content = buildPlanTemplate({ mode, hint, now: nowFn() })
-  try {
-    writeFile(planPath, content, 'utf8')
-  } catch (err) {
-    log(`flow plan: не вдалося записати ${planPath} — ${err instanceof Error ? err.message : String(err)}`)
-    return 1
-  }
-
-  log(`flow plan: створено ${planPath}`)
-
-  // Виводимо контекст для агента на stdout
-  const outLines = [
-    `## flow plan context`,
-    ``,
-    `mode: ${mode}`,
-    hint ? `hint: ${hint}` : `hint: (не задано — агент вирішує сам)`,
-    `plan: plan_${num}.md`,
-    ``
-  ]
-  // Додаємо вміст task.md для контексту (без front-matter)
-  outLines.push(`### task.md`)
-  const bodyStart = taskContent.indexOf('\n---\n', 4)
-  const taskBody = bodyStart !== -1 ? taskContent.slice(bodyStart + 5).trimStart() : taskContent
-  outLines.push(taskBody.trimEnd())
-
-  console.log(outLines.join('\n'))
-
-  return 0
-}