@nitra/cursor 4.1.2 → 5.0.1

package/scripts/dispatcher/graph.mjs

@@ -1,212 +0,0 @@
-/**
- * `n-cursor graph` — read-only позиція DAG вузлів (контракт
- * `docs/specs/2026-06-01-node-dag-state.md`). Перший зріз: `status` —
- * сканує `docs/graphs/<g>/nodes/*.md`, групує файли по вузлах, деривує статус
- * (done/failed/awaiting-human/in_progress/ready/blocked) і друкує таблицю.
- *
- * Стан — у файлах; нічого не мутує. FS (`readdir`/`readFile`/`exists`)
- * ін'єктується — тестується без диска. claim/tick/dispatch — наступні зрізи.
- */
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { cwd as processCwd } from 'node:process'
-
-import { parseFrontMatter } from './trace.mjs'
-
-/** Суфікси-артефакти вузла без qid. */
-const PLAIN = [
-  ['.plan', 'plan'],
-  ['.claim', 'claim'],
-  ['.fact', 'fact']
-]
-/** Префікси-артефакти з qid (`.ask-<qid>`, `.ans-<qid>`). */
-const QID = [
-  ['.ask-', 'ask'],
-  ['.ans-', 'ans']
-]
-
-/**
- * Класифікує файл-артефакт вузла за назвою.
- * @param {string} name назва файлу (напр. `B02-parser.ask-q1.md`)
- * @returns {{ stem: string, kind: string, qid?: string } | null} класифікація або null
- */
-export function classifyArtifact(name) {
-  if (!name.endsWith('.md')) return null
-  const base = name.slice(0, -'.md'.length)
-  for (const [suffix, kind] of PLAIN) {
-    if (base.endsWith(suffix)) return { stem: base.slice(0, -suffix.length), kind }
-  }
-  for (const [prefix, kind] of QID) {
-    const i = base.lastIndexOf(prefix)
-    if (i !== -1) return { stem: base.slice(0, i), kind, qid: base.slice(i + prefix.length) }
-  }
-  return null
-}
-
-/**
- * Парсить inline-список `[A, B]` із front-matter у масив id.
- * @param {string | null | undefined} value значення поля
- * @returns {string[]} елементи (trim, без порожніх)
- */
-export function parseIdList(value) {
-  if (typeof value !== 'string') return []
-  return value
-    .replace('[', '')
-    .replace(']', '')
-    .split(',')
-    .map(s => s.trim())
-    .filter(Boolean)
-}
-
-/**
- * Сканує вузли графа: групує файли по stem, читає plan/fact front-matter.
- * @param {string} root корінь репо
- * @param {string} graph id графа (каталог `docs/graphs/<graph>`)
- * @param {{ readdir?: (dir: string) => string[], readFile?: (file: string) => string }} [deps] ін'єкції FS
- * @returns {{ id: string, slug: string, dependsOn: string[], owner: string | null, hasClaim: boolean, hasFact: boolean, factStatus: string | null, asks: string[], answered: string[] }[]} вузли
- */
-export function scanGraph(root, graph, deps = {}) {
-  const readdir = deps.readdir ?? (dir => (existsSync(dir) ? readdirSync(dir) : []))
-  const readFile = deps.readFile ?? (file => readFileSync(file, 'utf8'))
-  const dir = join(root, 'docs', 'graphs', graph, 'nodes')
-
-  const byStem = new Map()
-  const ensure = stem => {
-    if (!byStem.has(stem)) {
-      byStem.set(stem, {
-        stem,
-        id: stem.split('-')[0],
-        slug: stem.slice(stem.indexOf('-') + 1),
-        dependsOn: [],
-        owner: null,
-        hasClaim: false,
-        hasFact: false,
-        factStatus: null,
-        asks: [],
-        answered: []
-      })
-    }
-    return byStem.get(stem)
-  }
-
-  for (const name of readdir(dir)) {
-    const art = classifyArtifact(name)
-    if (!art) continue
-    const node = ensure(art.stem)
-    switch (art.kind) {
-      case 'plan': {
-        const fm = parseFrontMatter(readFile(join(dir, name))) ?? {}
-        node.id = fm.id ?? node.id
-        node.dependsOn = parseIdList(fm.dependsOn)
-        node.owner = fm.owner ?? null
-        break
-      }
-      case 'claim': {
-        node.hasClaim = true
-        break
-      }
-      case 'fact': {
-        const fm = parseFrontMatter(readFile(join(dir, name))) ?? {}
-        node.hasFact = true
-        node.factStatus = fm.status ?? 'done'
-        break
-      }
-      case 'ask': {
-        node.asks.push(art.qid)
-        break
-      }
-      case 'ans': {
-        node.answered.push(art.qid)
-        break
-      }
-      // no default
-    }
-  }
-  return [...byStem.values()]
-}
-
-/**
- * Деривує статус одного вузла (чиста).
- * @param {{ hasFact: boolean, factStatus: string | null, hasClaim: boolean, asks: string[], answered: string[], dependsOn: string[] }} node вузол
- * @param {Set<string>} doneSet id вузлів зі статусом done
- * @returns {'done' | 'failed' | 'awaiting-human' | 'in_progress' | 'ready' | 'blocked'} статус
- */
-export function deriveStatus(node, doneSet) {
-  if (node.hasFact) return node.factStatus === 'failed' ? 'failed' : 'done'
-  const openAsk = node.asks.some(q => !node.answered.includes(q))
-  if (node.hasClaim && openAsk) return 'awaiting-human'
-  if (node.hasClaim) return 'in_progress'
-  if (node.dependsOn.every(d => doneSet.has(d))) return 'ready'
-  return 'blocked'
-}
-
-/**
- * Деривує статуси всіх вузлів графа (спершу doneSet із fact done).
- * @param {object[]} nodes вузли зі `scanGraph`
- * @returns {object[]} вузли з полем `status`
- */
-export function deriveGraph(nodes) {
-  const doneSet = new Set(nodes.filter(n => n.hasFact && n.factStatus !== 'failed').map(n => n.id))
-  return nodes.map(n => ({ ...n, status: deriveStatus(n, doneSet) }))
-}
-
-/**
- * Текстовий рендер позиції графа.
- * @param {string} graph id графа
- * @param {object[]} nodes вузли з полем `status`
- * @returns {string} людино-читабельна таблиця
- */
-export function renderGraph(graph, nodes) {
-  if (nodes.length === 0) return `граф ${graph}: вузлів не знайдено`
-  const order = ['in_progress', 'awaiting-human', 'ready', 'blocked', 'failed', 'done']
-  const counts = order
-    .map(s => [s, nodes.filter(n => n.status === s).length])
-    .filter(([, c]) => c > 0)
-    .map(([s, c]) => `${s}:${c}`)
-    .join(' ')
-  const lines = [`граф ${graph} — ${counts}`]
-  for (const n of nodes) {
-    const owner = n.owner ? ` ${n.owner}` : ''
-    const deps = n.dependsOn.length > 0 ? ` ←[${n.dependsOn.join(',')}]` : ''
-    lines.push(`  ${n.id} · ${n.slug} [${n.status}]${owner}${deps}`)
-  }
-  return lines.join('\n')
-}
-
-/**
- * Перелік графів (каталоги в `docs/graphs/`).
- * @param {string} root корінь репо
- * @param {(dir: string) => string[]} readdir інжектована readdir
- * @returns {string[]} id графів
- */
-function listGraphs(root, readdir) {
-  return readdir(join(root, 'docs', 'graphs'))
-}
-
-/**
- * CLI `n-cursor graph <status> [graph]`. Read-only.
- * @param {string[]} args аргументи після `graph`
- * @param {{ cwd?: string, readdir?: (dir: string) => string[], readFile?: (file: string) => string, log?: (m: string) => void }} [deps] ін'єкції
- * @returns {number} exit code (0 ok, 1 невідома підкоманда)
- */
-export function runGraphCli(args, deps = {}) {
-  const root = deps.cwd ?? processCwd()
-  const readdir = deps.readdir ?? (dir => (existsSync(dir) ? readdirSync(dir) : []))
-  const log = deps.log ?? console.log
-  const [sub, graphArg] = args
-
-  if (sub !== 'status') {
-    log('Usage: n-cursor graph status [<graph>]')
-    return 1
-  }
-
-  const graphs = graphArg ? [graphArg] : listGraphs(root, readdir)
-  if (graphs.length === 0) {
-    log('graph: у docs/graphs/ немає графів')
-    return 0
-  }
-  for (const g of graphs) {
-    log(renderGraph(g, deriveGraph(scanGraph(root, g, { readdir, readFile: deps.readFile }))))
-  }
-  return 0
-}

package/scripts/dispatcher/index.mjs

@@ -1,45 +0,0 @@
-/**
- * CLI-диспетчер `n-cursor flow` (думка.MD — протокол всередині вузла графу).
- *
- * flow plan    — Stage 1: читає task.md, створює plan_NNN.md, виводить контекст
- * flow verify  — Stage 2: структурний check + ## Done when + outputs на stdout
- * flow done    — CWD → node path → `graph done <path>`
- * flow audit   — CWD → node path → pending-audit_NNN.md → `graph audit <path>`
- * flow failed  — CWD → node path → `graph failed <path>`
- * flow spawn   — CWD → node path → `graph spawn <path>`
- */
-import { cmdPlan as plan } from './graph/lib/cmd-plan.mjs'
-import { cmdVerify as verify } from './graph/lib/cmd-verify.mjs'
-import { cmdAudit as audit, cmdDone as done, cmdFailed as failed, cmdSpawn as spawn } from './graph/lib/cmd-signals.mjs'
-
-const USAGE = [
-  'Usage:',
-  '  npx @nitra/cursor flow plan     # Stage 1: читає task.md, створює plan_NNN.md',
-  '  npx @nitra/cursor flow verify   # Stage 2: структурна перевірка + stdout-контекст для агента',
-  '  npx @nitra/cursor flow done     # успіх → graph done <node-path>',
-  '  npx @nitra/cursor flow audit    # аудит → pending-audit_NNN.md → graph audit <node-path>',
-  '  npx @nitra/cursor flow failed   # провал → graph failed <node-path>',
-  '  npx @nitra/cursor flow spawn    # розклад → graph spawn <node-path>'
-].join('\n')
-
-/**
- * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
- */
-export const DEFAULT_HANDLERS = { plan, verify, done, audit, failed, spawn }
-
-/**
- * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й
- * маршрутизує до handler-а. Невідома/відсутня підкоманда → usage + код 1.
- * @param {string[]} args аргументи після `flow`
- * @param {{ handlers?: Record<string, (rest: string[], deps: object) => Promise<number>> }} [deps] ін'єкція handler-ів (для тестів)
- * @returns {Promise<number>} exit code
- */
-export async function runFlowCli(args, deps = {}) {
-  const [sub, ...rest] = args
-  const handlers = deps.handlers ?? DEFAULT_HANDLERS
-  if (!sub || !Object.hasOwn(handlers, sub)) {
-    console.error(USAGE)
-    return 1
-  }
-  return await handlers[sub](rest, deps)
-}

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

@@ -1,348 +0,0 @@
-# active.mjs — Активний Раннер flow-диспетчера
-
-## Огляд
-
-Модуль `active.mjs` реалізує **Активний Раннер** диспетчера потоків (Фасад B, spec §8.1) — повний 5-фазний життєвий цикл автоматизованого виконання задачі в ізольованому git-worktree. Він зшиває чотири підсистеми в одну CLI-команду:
-
-1. `ensureWorktree` — підготовка ізольованого worktree під цільову гілку;
-2. `planner.generatePlan` — побудова покрокового плану через LLM-runner;
-3. `executor.executePlan` — послідовне виконання кроків з verify/commit;
-4. `reviewer.runReview` — gate-перевірки (verify) після кожного кроку.
-
-Усі IO-залежності (`runner`, `verify`, `commit`, `run`, `now`, `log`) **ін'єктуються** через об'єкт `deps`, тож модуль повністю тестується без реальних LLM, git-операцій чи gate-команд. У автономному режимі (`--autonomous`) runner додатково обгортається `withBudget` (§9.4) для жорсткого обмеження API-викликів і вартості.
-
-Експортується чотири CLI-обробники:
-
-- `run` — повний цикл build (ensureWorktree → план → executor);
-- `resume` — продовження з чекпойнта зі скиданням часткового доробку (safe-resume, §4.1.7);
-- `cancel` — прибирання transient sibling-файлів стану;
-- `repair` — діагностика стану або жорстке скидання робочого дерева до HEAD.
-
-Файл стану (`flow.json`), журнал подій (`flow.events.jsonl`) та lock-файли розташовуються поруч із worktree-кореневою текою; шляхи до них формують `flowStatePath` / `flowEventsPath` зі `state-store.mjs` та `events.mjs`.
-
-## Експорти / API
-
-| Експорт                | Тип              | Призначення                                                       |
-| ---------------------- | ---------------- | ----------------------------------------------------------------- |
-| `run(rest, deps?)`     | `async function` | Команда `flow run` — повний цикл build (планування + виконання).  |
-| `resume(_rest, deps?)` | `async function` | Команда `flow resume` — продовжити з останнього чекпойнта.        |
-| `cancel(_rest, deps?)` | `async function` | Команда `flow cancel` — прибрати транзитні sibling-и стану.       |
-| `repair(rest, deps?)`  | `async function` | Команда `flow repair [--discard-step-work]` — fail-closed escape. |
-
-Усі експорти повертають `Promise<number>` — exit code процесу:
-
-- `0` — успіх (`done` або no-op);
-- `1` — fail (помилка, нема стану/плану, бюджет вичерпано, стан пошкоджено);
-- `2` — `blocked-on-human` (потрібне HITL-втручання).
-
-### Внутрішні (не експортовані) helper-и
-
-| Ім'я                      | Призначення                                                                          |
-| ------------------------- | ------------------------------------------------------------------------------------ |
-| `defaultCommit(cwd, msg)` | Дефолтний commit-стратег: `git add -A && git commit -m <msg>` у worktree.            |
-| `defaultVerify(cwd)`      | Дефолтний verify: проганяє `runReview` з реальним `run` і `fingerprint: () => null`. |
-| `readFlowAutonomous(cwd)` | Зчитує секцію `flow.autonomous` з `.n-cursor.json` (бюджет автономки).               |
-
-## Функції
-
-### `defaultCommit(cwd, msg)`
-
-**Сигнатура:** `function defaultCommit(cwd: string, msg: string): void`
-
-**Параметри:**
-
-- `cwd` — абсолютний шлях до worktree;
-- `msg` — повідомлення коміту.
-
-**Повертає:** `void`.
-
-**Side effects:** виконує два синхронних `spawnSync('git', …)`-виклики у вказаному `cwd`:
-
-1. `git add -A` — індексує всі зміни;
-2. `git commit -m <msg>` — створює коміт.
-
-Помилки git **не пробрасуються** — exit code spawnSync ігнорується (виклик «оптимістичний»).
-
-### `defaultVerify(cwd)`
-
-**Сигнатура:** `function defaultVerify(cwd: string): { pass: boolean, failedOutput: string | null }`
-
-**Параметри:**
-
-- `cwd` — корінь worktree, де крутитимуться gate-команди.
-
-**Повертає:** verdict від `runReview` — об'єкт із полями `pass: boolean` та `failedOutput: string | null`.
-
-**Side effects:** делегує `runReview` зі `./reviewer.mjs`, передаючи реальний `run = realRun` (синхронний spawn зі `./commands.mjs`) та `fingerprint: () => null` (порівняння за хешем артефактів вимкнено).
-
-### `readFlowAutonomous(cwd)`
-
-**Сигнатура:** `function readFlowAutonomous(cwd: string): { maxApiCalls?: number, maxCostUsd?: number, onBudgetExceeded?: string }`
-
-**Параметри:**
-
-- `cwd` — корінь проєкту, де лежить `.n-cursor.json`.
-
-**Повертає:** об'єкт із секції `flow.autonomous` конфігу або порожній `{}`, якщо файл відсутній/невалідний.
-
-**Side effects:** **синхронно** читає `<cwd>/.n-cursor.json` через `readFileSync`. Будь-яка помилка (відсутній файл, невалідний JSON) глушиться `try/catch` → повертається `{}`.
-
-### `run(rest, deps?)`
-
-**Сигнатура:**
-
-```
-async function run(
-  rest: string[],
-  deps?: {
-    runner?: object,
-    verify?: (cwd: string) => { pass: boolean, failedOutput: string | null },
-    commit?: (cwd: string, msg: string) => void,
-    run?: (cmd: string, args: string[], opts: object) => object,
-    autonomous?: boolean,
-    budget?: { maxApiCalls?: number, maxCostUsd?: number, onBudgetExceeded?: string },
-    cwd?: string,
-    log?: (m: string) => void,
-    now?: () => number
-  }
-): Promise<number>
-```
-
-**Параметри:**
-
-- `rest` — позиційні аргументи CLI, можуть містити прапор `--autonomous` плюс `<branch> <task...>`;
-- `deps` — об'єкт ін'єкцій:
-  - `runner` — готовий subagent-runner (інакше створюється через `createRunner(deps)`);
-  - `verify` — кастомний verify-callback (дефолт: `defaultVerify`);
-  - `commit` — кастомний commit-callback (дефолт: `defaultCommit`);
-  - `run` — низькорівневий spawn-аналог (пробрасується далі в `ensureWorktree` / `createRunner`);
-  - `autonomous` — примусово вмикає budget guard незалежно від `rest`;
-  - `budget` — явний конфіг бюджету (інакше читається з `.n-cursor.json`);
-  - `cwd` — корінь проєкту для читання конфігу (дефолт: `process.cwd()`);
-  - `log` — логер (дефолт: `console.error`);
-  - `now` — постачальник часу (дефолт: `Date.now`).
-
-**Повертає:** `Promise<number>` — exit code:
-
-- `0` — `result.status === 'done'`;
-- `1` — `ensureWorktree` повернув ненульовий код, runner не створився, або executor дав помилку / `BudgetExceeded` / інший fail-стан;
-- `2` — `result.status === 'blocked-on-human'`.
-
-**Потік:**
-
-1. Підготовка: `log`, `now`, прапор `autonomous` (з `deps.autonomous` або `rest.includes('--autonomous')`), позиційні аргументи (фільтр без `--`-флагів).
-2. `ensureWorktree(positional, deps)` → якщо `code !== 0`, повертає цей же код. Інакше отримуємо `{ worktreeDir, branch, desc, baseCommit }`.
-3. `writeState(statePath, …)` — ініціальний стан із `status: 'in_progress'`, `started_at` у ISO, `metadata.base_commit`, порожнім `plan`.
-4. Створення runner-а: `deps.runner ?? await createRunner(deps)`. Якщо `createRunner` кинув — лог `run: <msg>` і `return 1`.
-5. Якщо `autonomous`: `runner = withBudget(runner, { maxApiCalls: budget.maxApiCalls, log })`.
-6. **try-блок:**
-   - `plan = await generatePlan({ runner, task: desc, cwd: worktreeDir })`;
-   - `updateState(statePath, s => ({ ...s, plan }))`;
-   - `result = await executePlan({ statePath, eventsPath: flowEventsPath(worktreeDir) }, { runner, verify, commit, cwd: worktreeDir, log, now })`;
-   - якщо `result.status === 'done'` — лог `'run: build done — далі \`flow release\`'`, `return 0`;
-   - якщо `result.status === 'blocked-on-human'` — лог `run: blocked-on-human на кроці <step>`, `return 2`;
-   - інакше `return 1`.
-7. **catch:** якщо `error instanceof BudgetExceeded` — лог `run: <msg> — abort`, оновлення стану на `status: 'failed'`, `return 1`. Будь-яка інша помилка — лог і `return 1`.
-
-**Side effects:** створення worktree, запис/оновлення `flow.json`, запис подій у `flow.events.jsonl`, виклики LLM-runner, commit-и в worktree, виконання verify-gate-ів.
-
-### `resume(_rest, deps?)`
-
-**Сигнатура:**
-
-```
-async function resume(
-  _rest: string[],
-  deps?: {
-    runner?: object,
-    verify?: (cwd: string) => object,
-    commit?: (cwd: string, msg: string) => void,
-    run?: (cmd: string, args: string[], opts: object) => object,
-    cwd?: string,
-    log?: (m: string) => void,
-    now?: () => number
-  }
-): Promise<number>
-```
-
-**Параметри:** `_rest` ігнорується; `deps` — як у `run`, мінус `autonomous`/`budget`.
-
-**Повертає:** `0` / `1` / `2` — як у `run`.
-
-**Потік (Safe-resume, §4.1.7):**
-
-1. `cwd = deps.cwd ?? process.cwd()`, `log`, `now`, `run_ = deps.run ?? realRun`.
-2. `state = readState(flowStatePath(cwd))`. Якщо `state` falsy — лог `'resume: стану нема'`, `return 1`.
-3. `openHitl = (state.hitl ?? []).filter(q => !q.answer)`. Якщо `status === 'blocked-on-human'` і `openHitl.length > 0` — лог `resume: ще blocked — N відкритих HITL-питань (заповни answer і повтори)`, `return 2`.
-4. Якщо `!state.plan?.length` — лог `'resume: нема плану'`, `return 1`.
-5. **Скидання часткового доробку:** `run_('git', ['reset', '--hard', 'HEAD'], { cwd })`.
-6. **HITL-злиття:** із відповідей будується `Map<step, answer>`; план переписується так, що **завершені** кроки (`status === 'done'`) не зачіпаються, а **інші** дістають `retry_count: 0` і — якщо є відповідь на цей крок — поле `hint: <answer>`. HITL-питання з відповіддю переводяться у `status: 'answered'`.
-7. Створення runner-а: `deps.runner ?? await createRunner(deps)` (на помилку — `return 1`).
-8. `executePlan(...)` з тими ж дефолтами verify/commit, що й у `run`.
-9. Розбір `result.status`: `done → 0`, `blocked-on-human → 2`, інше → `1`.
-
-**Side effects:** `git reset --hard HEAD` (потенційно деструктивно для незакомічених змін!), мутація `flow.json`, виклики LLM, commit-и, verify.
-
-### `cancel(_rest, deps?)`
-
-**Сигнатура:**
-
-```
-async function cancel(
-  _rest: string[],
-  deps?: { cwd?: string, log?: (m: string) => void }
-): Promise<number>
-```
-
-**Параметри:** `_rest` ігнорується; `deps.cwd` (дефолт: `process.cwd()`), `deps.log` (дефолт: `console.error`).
-
-**Повертає:** завжди `0`.
-
-**Потік:** виклик `cleanupFlowSiblings(cwd)` (зі `./state-store.mjs`) → лог `'cancel: стан і sibling-и прибрано'` → `return 0`.
-
-**Side effects:** видалення `flow.json`, `flow.events.jsonl`, lock-файлів навколо worktree.
-
-### `repair(rest, deps?)`
-
-**Сигнатура:**
-
-```
-async function repair(
-  rest: string[],
-  deps?: {
-    run?: (cmd: string, args: string[], opts: object) => object,
-    cwd?: string,
-    log?: (m: string) => void
-  }
-): Promise<number>
-```
-
-**Параметри:**
-
-- `rest` — аргументи CLI; перевіряється наявність `--discard-step-work`;
-- `deps.run` — низькорівневий spawn (дефолт: `realRun`);
-- `deps.cwd` — корінь worktree (дефолт: `process.cwd()`);
-- `deps.log` — логер (дефолт: `console.error`).
-
-**Повертає:** `0` — у двох випадках: успішне жорстке скидання або валідне читання стану (включно з «стану нема»); `1` — стан пошкоджено (виняток при `readState`).
-
-**Потік:**
-
-1. Якщо `rest.includes('--discard-step-work')`:
-   - `run_('git', ['reset', '--hard', 'HEAD'], { cwd })`;
-   - лог `'repair: робоче дерево скинуто до HEAD (--discard-step-work)'`;
-   - `return 0`.
-2. Інакше try-блок: `state = readState(flowStatePath(cwd))`. Лог `repair: стан валідний (status: <s.status>)` (якщо state truthy) або `'repair: стану нема'` (якщо falsy). `return 0`.
-3. На помилку читання — лог `repair: стан пошкоджено — <msg>. Спробуй \`flow repair --discard-step-work\` або \`flow cancel\`.`, `return 1`.
-
-**Side effects:** опціональний `git reset --hard HEAD` (деструктивно), синхронне читання файлу стану.
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-- `node:child_process` → `spawnSync` — синхронні git-команди в `defaultCommit`.
-- `node:fs` → `readFileSync` — читання `.n-cursor.json` у `readFlowAutonomous`.
-- `node:path` → `join` — побудова шляху до конфігу.
-- `node:process` → `cwd as processCwd` — дефолтний робочий каталог.
-
-### Внутрішні модулі (relative imports)
-
-- `./budget.mjs` → `BudgetExceeded`, `withBudget` — клас винятка для перевищення бюджету та обгортка runner-а з guard-ом (§9.4).
-- `./commands.mjs` → `ensureWorktree`, `realRun` — підготовка worktree та реальний spawn-runner.
-- `./events.mjs` → `flowEventsPath` — шлях до журналу подій (`flow.events.jsonl`).
-- `./executor.mjs` → `executePlan` — послідовне виконання плану з verify/commit/HITL.
-- `./planner.mjs` → `generatePlan` — побудова плану через LLM-runner на основі опису задачі.
-- `./reviewer.mjs` → `runReview` — запуск gate-перевірок (verify-callback за замовчуванням).
-- `./state-store.mjs` → `cleanupFlowSiblings`, `flowStatePath`, `readState`, `updateState`, `writeState` — IO навколо `flow.json` та sibling-файлів.
-- `./subagent-runner.mjs` → `createRunner` — фабрика LLM-runner-а (Claude/інший subagent) з ін'єкцій.
-
-## Потік виконання / Використання
-
-### CLI-команди (диспатчиться зовнішнім роутером)
-
-```
-flow run [--autonomous] <branch> "<task...>"
-flow resume
-flow cancel
-flow repair [--discard-step-work]
-```
-
-### Сценарій `flow run --autonomous feat/x "Add tests"`
-
-1. **ensureWorktree** створює (або підхоплює) worktree під гілку `feat/x`, повертає `worktreeDir`, базовий комміт, текстовий опис задачі (`desc`).
-2. У worktree пишеться початковий `flow.json` зі `status: 'in_progress'`, `started_at`, `metadata.base_commit`, порожнім планом.
-3. Створюється `runner` (Claude-subagent). У `--autonomous` режимі він обгортається `withBudget` з `maxApiCalls` з `.n-cursor.json` → `flow.autonomous`.
-4. `generatePlan` через LLM-runner будує покроковий план; план зберігається в стані.
-5. `executePlan` ітерує план: для кожного кроку викликає runner-а → verify-gate → commit (через `defaultCommit`); події логуються у `flow.events.jsonl`; стан оновлюється.
-6. Якщо verify падає, executor може відкрити HITL-питання → стан переходить у `blocked-on-human`, `run` повертає `2`.
-7. Якщо `withBudget` вистрелив `BudgetExceeded` — стан стає `failed`, exit `1`.
-
-### Сценарій `flow resume`
-
-Користувач заповнив `answer` у HITL-питаннях `flow.json` і запускає `flow resume`:
-
-1. Зчитується стан, відкриті (без `answer`) HITL → блокує `resume` з кодом `2`.
-2. `git reset --hard HEAD` повертає робоче дерево до останнього коміту (відкочуємо частковий доробок невдалого кроку).
-3. HITL-відповіді стають полями `hint` для відповідних кроків, `retry_count` обнуляється для незавершених кроків.
-4. `executePlan` стартує з того ж списку, але вже з підказками.
-
-### Сценарій `flow cancel`
-
-Прибирання залишків:
-
-- Видаляється `flow.json`, `flow.events.jsonl`, lock-файли — через `cleanupFlowSiblings(cwd)`.
-- Worktree як такий **не видаляється** — це окрема відповідальність команд worktree-менеджмента.
-
-### Сценарій `flow repair`
-
-- Без аргументів — діагностика: чи стан читається валідно;
-- `--discard-step-work` — жорсткий `git reset --hard HEAD` (свідома втрата незакомічених змін).
-
-### Тестування
-
-Усе IO ін'єктується через `deps`:
-
-```js
-import { run } from './active.mjs'
-
-const fakeRunner = {
-  /* mock */
-}
-const code = await run(['feat/x', 'task'], {
-  runner: fakeRunner,
-  verify: () => ({ pass: true, failedOutput: null }),
-  commit: () => {},
-  run: () => ({ status: 0, stdout: '', stderr: '' }),
-  cwd: '/tmp/proj',
-  log: () => {},
-  now: () => 0
-})
-```
-
-Це дозволяє тестам не торкатись реальних `git`, LLM чи gate-команд — лише перевіряти контракт переходів стану, exit-коди й послідовність викликів.
-
-## Rebuild Test
-
-Цей розділ верифікує, що документація відтворює поведінку файлу без звертання до самого `active.mjs`:
-
-1. Чотири експорти модуля: `run`, `resume`, `cancel`, `repair` — усі `async`, усі повертають exit code (`0`/`1`/`2`).
-2. У `run` спочатку викликається `ensureWorktree(positional, deps)`; якщо його `code !== 0`, цей самий код повертається без подальших дій.
-3. Прапор `--autonomous` визначається як `deps.autonomous ?? rest.includes('--autonomous')`; у позиційні аргументи `--`-флаги **не** потрапляють (фільтруються).
-4. Конфіг бюджету в `--autonomous` режимі береться з `deps.budget` або з `.n-cursor.json` → `flow.autonomous` (порожній `{}` при будь-якій помилці читання).
-5. Початковий стан у `run` має поля `branch`, `status: 'in_progress'`, `started_at` (ISO від `now()`), `metadata.base_commit`, `plan: []`.
-6. Помилка створення runner-а в `run`/`resume` → лог із префіксом `run:` / `resume:` і `return 1`.
-7. У try-блоці `run` спочатку `generatePlan`, потім `updateState` з планом, потім `executePlan`; усі три отримують `runner` та `worktreeDir`.
-8. Розбір `result.status` у `run` і `resume`: `done → 0`, `blocked-on-human → 2`, інше → `1`.
-9. `BudgetExceeded` у `run`: лог `<msg> — abort`, `updateState(... status: 'failed')`, `return 1`.
-10. `resume` блокує (exit `2`), якщо стан `blocked-on-human` і є HITL без `answer`.
-11. `resume` робить `git reset --hard HEAD` **перед** запуском runner-а — для скидання часткового доробку.
-12. У `resume` HITL-відповіді перетворюються на `hint` тільки для **незавершених** кроків; завершені (`status === 'done'`) не чіпаються.
-13. HITL-питання з `answer` отримують `status: 'answered'` у новому стані.
-14. `cancel` завжди повертає `0`; викликає `cleanupFlowSiblings(cwd)` і логує `'cancel: стан і sibling-и прибрано'`.
-15. `repair --discard-step-work` робить `git reset --hard HEAD` і повертає `0`.
-16. `repair` без аргументів: успішно зчитує стан (або `null`) → `0`; помилка читання → лог із префіксом `repair: стан пошкоджено —` та посиланням на `flow repair --discard-step-work` / `flow cancel`, `return 1`.
-17. `defaultCommit` робить два `spawnSync('git', …)` у `cwd`: `add -A`, потім `commit -m <msg>`.
-18. `defaultVerify` делегує `runReview({ run: realRun, cwd, fingerprint: () => null })`.
-19. Усі логери дефолтяться на `console.error`; усі джерела часу — на `Date.now`; усі `cwd` — на `process.cwd()`.
-20. Лог-повідомлення мають детерміновані префікси: `run:`, `resume:`, `cancel:`, `repair:` — це публічний контракт CLI-виводу для тестів і користувача.