@nitra/cursor 4.1.1 → 5.0.0

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

@@ -1,210 +0,0 @@
-# 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).

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

@@ -1,183 +0,0 @@
-# events.mjs — WAL-журнал подій `flow`
-
-## Огляд
-
-Модуль `events.mjs` реалізує **append-only WAL** (Write-Ahead Log) журнал подій для підсистеми `flow` (специфікація §4.1.2, §9). Журнал зберігається у sibling-файлі поряд із checkout-каталогом worktree: для `…/.worktrees/feat-x` файл подій має шлях `…/.worktrees/feat-x.events.jsonl` (формат JSON Lines — по одному JSON-об'єкту на рядок).
-
-Журнал є **єдиним** для двох категорій подій:
-
-- **Переходи стану** flow (наприклад, `step_started`, `step_completed`, `blocked` тощо).
-- **Облік API-викликів** (події типу `api_call`).
-
-Ключові інваріанти та властивості:
-
-- **Append-only**. Нові записи лише дописуються в кінець файлу. Це робить журнал **краш-безпечнішим** за повний перезапис: якщо аварія сталася посередині запису рядка, ушкоджений (торваний) рядок при читанні **толерується** — він просто пропускається, а решта журналу залишається валідною.
-- **WAL-інваріант**: подію слід дописати в журнал **ДО** оновлення високорівневого статусу у snapshot-файлі `.flow.json`. За дотримання цього інваріанта відповідає сторонній викликач — `state-store.recordTransition`.
-- **Усі шляхи — абсолютні**. Модуль явно валідує кожен вхідний `path` і кидає помилку для відносних шляхів (правило проекту `no-relative-fs-path`).
-
-Модуль використовує **синхронні** Node.js fs-API (`appendFileSync`, `readFileSync`, `existsSync`), що адекватно для коротких записів короткоживучих CLI/dispatcher-сценаріїв і гарантує лінійний порядок без race-conditions у межах одного процесу.
-
-## Експорти / API
-
-Усі експорти — іменовані ESM-функції.
-
-| Експорт                                | Тип                                         | Призначення                                                                                         |
-| -------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `flowEventsPath(worktreeDir)`          | `(string) => string`                        | Обчислити абсолютний шлях sibling-журналу для checkout-каталогу worktree.                           |
-| `appendEvent(eventsPath, event, now?)` | `(string, object, () => number?) => object` | Дописати одну подію (зі стампом `at`) у журнал; повертає фактично записаний об'єкт.                 |
-| `readEvents(eventsPath)`               | `(string) => object[]`                      | Прочитати всі події з журналу в порядку запису; відсутній файл → `[]`; невалідні рядки ігноруються. |
-
-Default-експорт відсутній.
-
-## Функції
-
-### `flowEventsPath(worktreeDir)`
-
-**Сигнатура.** `function flowEventsPath(worktreeDir: string): string`
-
-**Параметри.**
-
-- `worktreeDir` — **абсолютний** шлях до checkout-каталогу worktree (наприклад, `/repo/.worktrees/feat-x`).
-
-**Повертає.** Абсолютний шлях до sibling-файлу журналу подій: каталог-батько (`dirname(worktreeDir)`) + базове ім'я worktree + суфікс `.events.jsonl`. Наприклад, для входу `/repo/.worktrees/feat-x` повертається `/repo/.worktrees/feat-x.events.jsonl`.
-
-**Помилки.** Якщо `worktreeDir` не є абсолютним шляхом — кидає `Error` з префіксом `flowEventsPath: очікується абсолютний шлях …`.
-
-**Side effects.** Жодних. Чиста функція (працює лише з рядками через `path`-утиліти).
-
-**Деталі реалізації.** Використовує `dirname` і `basename` з `node:path`, що робить функцію крос-платформною щодо роздільників шляху (хоча в результаті завжди формується шлях у стилі поточної ОС).
-
-### `appendEvent(eventsPath, event, now?)`
-
-**Сигнатура.** `function appendEvent(eventsPath: string, event: object, now?: () => number): object`
-
-**Параметри.**
-
-- `eventsPath` — **абсолютний** шлях до файлу `.events.jsonl`.
-- `event` — об'єкт події, наприклад `{ type: 'step_started', step: 2 }`. Може містити довільні поля.
-- `now` — _необов'язкова_ фабрика часу, що повертає мілісекунди (за замовчуванням `Date.now`). Дозволяє **ін'єкцію** детермінованого часу у тестах.
-
-**Повертає.** Фактично записаний запис у формі `{ at, ...event }`, де `at` — ISO-рядок часу (`new Date(now()).toISOString()`). Поля переданого `event` накладаються **поверх** `at`, тому якщо в `event` уже є власне поле `at`, воно перепише згенероване (це може бути корисно для бек-філу/міграцій).
-
-**Side effects.**
-
-- **Файлова система**: дописує один рядок (`JSON.stringify(record) + '\n'`) у `eventsPath` через `appendFileSync` із кодуванням `utf8`. Якщо файлу не існує — він **створюється** автоматично (`appendFileSync` діє як append-or-create).
-- **Жодних мережевих, БД- чи stdout-ефектів.**
-
-**Помилки.**
-
-- Якщо `eventsPath` не абсолютний — кидає `Error` з префіксом `appendEvent: очікується абсолютний шлях …`.
-- Будь-яка помилка `appendFileSync` (відсутня тека-батько, права, EROFS тощо) пробрасується назовні як є.
-
-**Краш-безпека.** Якщо процес аварійно завершиться під час `appendFileSync`, у файлі може залишитися **частково записаний останній рядок**. Це навмисно толерується читачем (`readEvents`), тому WAL не вимагає fsync чи двофазного запису для базової стійкості.
-
-### `readEvents(eventsPath)`
-
-**Сигнатура.** `function readEvents(eventsPath: string): object[]`
-
-**Параметри.**
-
-- `eventsPath` — **абсолютний** шлях до файлу `.events.jsonl`.
-
-**Повертає.** Масив об'єктів-подій у тому самому порядку, в якому вони були дописані (хронологічний порядок append-only). Якщо файлу немає — повертається `[]`.
-
-**Side effects.** Лише читання файлу (`readFileSync`, `existsSync`). Файл **не модифікується** і **не створюється**.
-
-**Поведінка при пошкодженнях.**
-
-- Порожні рядки (включно з трейлінговим `\n` після останнього запису) **відфільтровуються** через `line.trim() !== ''`.
-- Кожен непорожній рядок намагається парситися як JSON. Якщо `JSON.parse` кидає виняток (наприклад, торваний останній рядок після краху під час `appendFileSync`), цей рядок **пропускається** (через `flatMap` + порожній масив у `catch`), і читання продовжується далі. Інші рядки повертаються нормально.
-- Це і є **append-only толерантність**: один пошкоджений запис не валить весь журнал.
-
-**Помилки.** Якщо `eventsPath` не абсолютний — кидає `Error` з префіксом `readEvents: очікується абсолютний шлях …`. Інші помилки fs (наприклад, EACCES при `readFileSync`) пробрасуються.
-
-**Складність.** Лінійна за розміром файлу (`O(N)`), читання здійснюється повністю в пам'ять. Для дуже довгих журналів варто розглянути потокове читання — модуль навмисно тримає просту синхронну реалізацію.
-
-## Залежності
-
-### Зовнішні (Node.js stdlib)
-
-- `node:fs`
-  - `appendFileSync` — атомарний (на рівні syscall) append одного запису.
-  - `existsSync` — перевірка наявності файлу перед читанням.
-  - `readFileSync` — повне читання файлу журналу.
-- `node:path`
-  - `basename`, `dirname`, `isAbsolute`, `join` — формування sibling-шляху і валідація абсолютних шляхів.
-
-### Внутрішні
-
-Модуль **не має внутрішніх імпортів**. Він — найнижчий рівень WAL-абстракції, на який спираються інші частини dispatcher/flow:
-
-- `state-store.recordTransition` (споживач) — викликає `appendEvent` перед оновленням `.flow.json` (забезпечення WAL-інваріанта).
-- Будь-який код обліку `api_call`-подій також використовує `appendEvent`.
-- Читачі (наприклад, інструменти діагностики, відновлення стану, аналітики) використовують `readEvents`.
-
-## Потік виконання / Використання
-
-### Типовий життєвий цикл подій worktree
-
-1. **Обчислення шляху журналу** — один раз на сесію/процес:
-   ```js
-   import { flowEventsPath, appendEvent, readEvents } from './events.mjs'
-   
-   const eventsPath = flowEventsPath('/repo/.worktrees/feat-x')
-   // → '/repo/.worktrees/feat-x.events.jsonl'
-   ```
-2. **Дозапис події під час переходу стану** (через `state-store.recordTransition`, що дотримується WAL-інваріанта):
-   ```js
-   appendEvent(eventsPath, { type: 'step_started', step: 2 })
-   // потім: оновити .flow.json
-   ```
-3. **Дозапис обліку API-виклику** (тим самим API, у тому ж файлі):
-   ```js
-   appendEvent(eventsPath, {
-     type: 'api_call',
-     provider: 'anthropic',
-     model: 'claude-opus',
-     tokens: 1234
-   })
-   ```
-4. **Читання історії** (наприклад, для відновлення стану або аудиту):
-   ```js
-   const events = readEvents(eventsPath)
-   for (const ev of events) {
-     // обробка ev.at, ev.type, …
-   }
-   ```
-
-### Сценарій краху
-
-1. `appendFileSync` починає писати рядок, процес гине посеред запису.
-2. Файл містить N−1 валідних рядків + один торваний (наприклад, без `}` і `\n` у кінці).
-3. На наступному старті `readEvents`:
-   - відфільтрує порожні рядки;
-   - спробує `JSON.parse` для кожного непорожнього;
-   - на торваному останньому отримає виняток → `flatMap` поверне `[]` для нього → запис **пропускається**;
-   - решта N−1 подій нормально потрапить у результат.
-4. Дані до моменту краху збережено; пошкоджений запис вважається втраченим — це прийнятна семантика append-only WAL.
-
-### Інваріанти, що накладає модуль
-
-- **Усі шляхи — абсолютні** (`isAbsolute` перевірка у всіх трьох експортах).
-- **Кодування файлу — UTF-8** (явно вказано як в `appendFileSync`, так і в `readFileSync`).
-- **Формат рядка — однорядковий JSON + `\n`** (jsonl).
-- **`at` — ISO-8601-рядок UTC** (через `Date.prototype.toISOString`).
-- **Порядок збереження — порядок дозапису** (нативна семантика append-only).
-
-### Чого модуль свідомо не робить
-
-- Не реалізує **rotation / compaction** журналу — це відповідальність вищих рівнів або інфраструктури worktree.
-- Не виконує **fsync** після кожного append — покладається на ОС-кеш та append-only толерантність читача.
-- Не валідує **схему події** — приймає будь-який `object` (контрактом структури подій відає `flow`-специфікація і споживачі).
-- Не обробляє **багатопроцесний конкурентний доступ** — для одного worktree передбачається один пишучий процес; для читача конкурентність безпечна, оскільки `appendFileSync` атомарно дозаписує цілий буфер.
-
-## Rebuild Test
-
-Документація достатня, щоб переписати модуль з нуля:
-
-- три іменовані експорти з точними сигнатурами;
-- формула sibling-шляху (`dirname` + `basename` + `.events.jsonl`);
-- WAL-інваріант і його носій (`state-store.recordTransition`);
-- формат запису (`{ at: ISO, ...event }`, `JSON.stringify` + `\n`, кодування UTF-8);
-- стратегія читання (`existsSync`-гард → split `\n` → фільтр порожніх → `JSON.parse` у `try/catch` + `flatMap`);
-- правила валідації абсолютних шляхів і повідомлення про помилки.

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

@@ -1,190 +0,0 @@
-# executor.mjs
-
-## Огляд
-
-Модуль `executor.mjs` — це **Фаза 3 (Ф3) диспетчера** з flow-специфікації: він покроково виконує план, що раніше зібрав `planner`, і просуває стан через журнал подій. Відповідно до спеки (§3 Ф3), кожен крок плану надсилається в субагент через **мікропромпт зі стану** — субагент бачить лише поточний крок, критерії приймання й, опційно, останню помилку (без історії переписки чи історії інших кроків).
-
-Базові інваріанти, які реалізовано в коді:
-
-- **Мікропромпт зі стану** (§3 Ф3): субагент отримує тільки поточний крок + критерії + останню помилку, а не повний контекст ланцюга кроків.
-- **Commit лише після зеленого `verify`** (§4.1.7): жоден repair-прохід не комітиться, тому `HEAD` git-репозиторію завжди вказує на останній «зелений» крок плану.
-- **Repair обмежений `maxRepairAttempts`** (за замовчуванням 3): коли спроби вичерпано, виконання переходить у режим `blocked-on-human` (HITL, §4.2) і записує питання в `state.hitl`.
-
-Усі побічні дії (запуск субагента, верифікація, commit, годинник) **інжектуються** через об’єкт `deps`. Це робить модуль повністю детермінованим і тестованим: реальний LLM, git і ворота (gates) не викликаються з нього напряму.
-
-## Експорти / API
-
-Модуль експортує три функції (ESM, named exports):
-
-| Експорт       | Тип        | Призначення                                                                                                                          |
-| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `microprompt` | `function` | Чиста функція побудови тексту мікропромпта для конкретного кроку плану.                                                              |
-| `patchStep`   | `function` | Чиста функція, що повертає новий обʼєкт стану з оновленим кроком за індексом (immutable update).                                     |
-| `executePlan` | `async`    | Головна функція: читає стан, ітерує план, дергає `runner`/`verify`/`commit`, записує транзиції стану та повертає підсумковий статус. |
-
-Default-експорту немає.
-
-## Функції
-
-### `microprompt(step, state)`
-
-**Сигнатура:**
-
-```js
-function microprompt(step, state) → string
-```
-
-**Параметри:**
-
-- `step` — обʼєкт поточного кроку плану. Очікувані поля:
-  - `step` (`number`) — номер кроку (для людини).
-  - `task` (`string`) — формулювання задачі кроку.
-  - `acceptance` (`string`, опційно) — критерії приймання.
-  - `hint` (`string`, опційно) — підказка від людини (HITL).
-  - `last_error` (`string`, опційно) — останній текст помилки `verify` для repair-спроби.
-- `state` — поточний стан flow. Використовується лише поле `state.branch` для рядка «Гілка: …» (якщо немає — підставляється `'—'`).
-
-**Повертає:** рядок-промпт, який скріплює кілька рядків через `\n`:
-
-1. Заклик зробити **рівно** один крок плану з нагадуванням про Iron Law of TDD (спершу падаючі тести, тоді код).
-2. `Гілка: <state.branch ?? '—'>`.
-3. `Крок <step.step>: <step.task>`.
-4. (Якщо є `acceptance`) `Критерії приймання: …`.
-5. (Якщо є `hint`) `Підказка людини (HITL): …`.
-6. (Якщо є `last_error`) `Попередня спроба впала на перевірці:\n<last_error>\nВиправ це.`.
-
-**Side effects:** немає — це чиста функція форматування.
-
-### `patchStep(state, index, patch)`
-
-**Сигнатура:**
-
-```js
-function patchStep(state, index, patch) → newState
-```
-
-**Параметри:**
-
-- `state` — обʼєкт стану з масивом `state.plan` (`object[]`).
-- `index` (`number`) — індекс кроку в `state.plan`, який треба оновити.
-- `patch` (`object`) — поля, які треба змерджити в крок (`{ ...step, ...patch }`).
-
-**Повертає:** новий обʼєкт стану `{ ...state, plan: [...] }`, де крок під `index` замінено на `{ ...step, ...patch }`, інші кроки залишаються тими самими посиланнями.
-
-**Side effects:** немає — immutable update через `Array.prototype.map`.
-
-### `executePlan(paths, deps)`
-
-**Сигнатура:**
-
-```js
-async function executePlan(paths, deps) → Promise<{ status: 'done' | 'blocked-on-human', step?: number }>
-```
-
-**Параметри:**
-
-- `paths` — обʼєкт зі шляхами до файлів стану й журналу подій:
-  - `paths.statePath` — шлях до файлу стану, що читається `readState`.
-  - `paths.eventsPath` — шлях до журналу подій (передається далі в `recordTransition`).
-- `deps` — обʼєкт ін’єкцій:
-  - `runner` (обовʼязково) — обʼєкт із методом `runStep(prompt, opts?)`. Викликається з мікропромптом і `{ cwd }`.
-  - `verify` (обовʼязково) — `(cwd) → { pass: boolean, failedOutput?: string }` або проміс такого ж обʼєкта. Поле `pass` визначає, чи крок зелений; `failedOutput` йде у `last_error`.
-  - `commit` (обовʼязково) — `(cwd, msg) → void`. Викликається **лише** після зеленого `verify`, з повідомленням `flow: step <N> — <task>`.
-  - `cwd` (опційно) — робочий каталог, який передається `runner` і `verify`/`commit`.
-  - `maxRepairAttempts` (`number`, за замовчуванням `3`) — максимальна кількість repair-спроб на крок (перша спроба теж рахується в `retry_count`).
-  - `log` (`(msg) => void`, за замовчуванням `() => {}`) — лоґер прогресу.
-  - `now` (`() => number`, за замовчуванням `Date.now`) — джерело часу для `recordTransition`.
-
-**Повертає:**
-
-- `{ status: 'done' }` — якщо всі кроки плану позначено `done`, фінальна транзиція `plan_done` піднімає `state.status = 'built'`.
-- `{ status: 'blocked-on-human', step: <N> }` — якщо на якомусь кроці вичерпано `maxRepairAttempts`. Тоді у стан додано HITL-питання й виставлено `state.status = 'blocked-on-human'`.
-
-**Кидає:** `Error('executor: у стані немає плану — спершу planner')` — якщо `readState` повертає порожній обʼєкт або `plan` відсутній/порожній.
-
-**Side effects:**
-
-- Читає файл стану через `readState(paths.statePath)`.
-- Записує транзиції в журнал/стан через `recordTransition(paths, event, reducer, now)` для подій: `step_done`, `step_retry`, `blocked`, `plan_done`.
-- Викликає `runner.runStep(...)` — потенційний LLM/субагент-виклик.
-- Викликає `verify(cwd)` — потенційний запуск тестів/гейтів.
-- Викликає `commit(cwd, msg)` — git-commit; **тільки** при зеленому `verify`.
-- Записує повідомлення через `log(...)`.
-
-## Залежності
-
-### Внутрішні модулі (імпорти)
-
-- `./state-store.mjs`:
-  - `readState(statePath)` — синхронне читання обʼєкта стану з диска.
-  - `recordTransition(paths, event, reducer, now)` — атомарне оновлення стану й запис події в `events`-журнал; повертає новий стан.
-
-### Інжектовані залежності (через `deps`)
-
-- `runner.runStep` — реалізація запуску субагента (наприклад, `subagent-runner.mjs`).
-- `verify` — функція верифікації (наприклад, обгортка над тест-командою/ворітьми).
-- `commit` — функція git-комміту.
-- `log`, `now` — необовʼязкові утиліти.
-
-### Зовнішні залежності
-
-Стандартних модулів Node.js немає у файлі напряму — увесь I/O делеговано в `state-store.mjs` та інжектовані залежності.
-
-## Потік виконання / Використання
-
-### Алгоритм `executePlan`
-
-1. **Деструктуризація `deps`** з дефолтами: `maxRepairAttempts = 3`, `log = noop`, `now = Date.now`.
-2. **Зчитування стану**: `state = readState(paths.statePath)`. Якщо `state?.plan` відсутній або порожній — кидається помилка `executor: у стані немає плану — спершу planner`.
-3. **Ітерація плану** циклом `for (let i = 0; i < state.plan.length; i++)`:
-   - Якщо крок уже `status === 'done'` — пропустити (resume-friendly).
-   - Інакше зайти у внутрішній `while`-цикл, поки `retry_count < maxRepairAttempts` і `done === false`:
-     1. Зчитати свіжий `step = state.plan[i]`.
-     2. Залогувати: `executor: крок N (спроба M)`, де `M = retry_count + 1`.
-     3. `await runner.runStep(microprompt(step, state), { cwd })` — виконати крок субагентом з мікропромптом.
-     4. `verdict = await verify(cwd)` — перевірити результат.
-     5. **Якщо `verdict.pass === true`:**
-        - `commit(cwd, "flow: step <step.step> — <step.task>")`.
-        - `recordTransition(paths, { type: 'step_done', step }, s => patchStep(s, i, { status: 'done' }), now)`.
-        - `done = true`, вихід з `while`.
-     6. **Інакше (red):**
-        - `recordTransition` із подією `step_retry`, що інкрементує `retry_count` і кладе `last_error: verdict.failedOutput ?? null`.
-        - `while` повторює спробу (наступна ітерація прочитає вже оновлений `state.plan[i]`).
-4. **Якщо `while` вийшов з `done === false`** (тобто всі спроби спалено):
-   - Будується HITL-питання `{ id: 'q-<i>', step, question: '…не проходить verify після N спроб…', status: 'open', answer: '' }`.
-   - `recordTransition` із подією `blocked`, що ставить `state.status = 'blocked-on-human'` і додає питання в `state.hitl`.
-   - Повертається `{ status: 'blocked-on-human', step: failed.step }` — подальші кроки не запускаються.
-5. **Після успішного проходу всіх кроків** записується фінальна транзиція `plan_done`, що піднімає `state.status = 'built'`, і функція повертає `{ status: 'done' }`.
-
-### Інваріанти, які тримає алгоритм
-
-- **HEAD git завжди зелений**: `commit` викликається тільки в гілці `verdict.pass === true`. Жодна repair-спроба не записується в git.
-- **Стан eventsourcing-friendly**: усі зміни плану й верхнього статусу йдуть через `recordTransition`, тож у журналі подій лежить повна історія `step_done` / `step_retry` / `blocked` / `plan_done`.
-- **Resume-семантика**: при повторному виклику `executePlan` уже виконані кроки (`status === 'done'`) пропускаються; кроки з частковим `retry_count` продовжаться з того ж лічильника, але вже без обнулення (поки лічильник менший за `maxRepairAttempts`).
-- **Мінімальний контекст субагента**: усе, що знає субагент про задачу — це повернений `microprompt(step, state)`; жодного «склейного» історичного контексту в нього не передається.
-
-### Приклад використання
-
-```js
-import { executePlan } from './executor.mjs'
-
-const result = await executePlan(
-  { statePath: '.flow/state.json', eventsPath: '.flow/events.jsonl' },
-  {
-    runner: subagentRunner, // { runStep(prompt, { cwd }) }
-    verify: async cwd => runGates(cwd), // { pass, failedOutput }
-    commit: (cwd, msg) => gitCommit(cwd, msg),
-    cwd: process.cwd(),
-    maxRepairAttempts: 3,
-    log: m => console.error(m)
-  }
-)
-
-if (result.status === 'blocked-on-human') {
-  // потрібна відповідь людини у state.hitl[] для кроку result.step
-}
-```
-
-### Інтеграція в диспетчер
-
-`executor.mjs` — третя фаза (Ф3) flow-диспетчера, що йде після `planner.mjs` (який наповнює `state.plan`) і працює зі сховищем стану `state-store.mjs`. Цей файл не знає про конкретні CLI-команди диспетчера — він викликається з `commands.mjs`/`active.mjs` або тестів, де користувач підставляє реальні реалізації `runner`, `verify`, `commit`.