@nitra/cursor 4.1.1 → 5.0.0

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

@@ -1,232 +0,0 @@
-# artifact.mjs
-
-## Огляд
-
-Модуль `artifact.mjs` — це набір **спільних утиліт для фаз `spec` і `plan`** у моделі «Пасивний Турнікет» dispatcher-конвеєра. Він вирішує три задачі:
-
-1. **Резолв traceable-артефакту** в каталозі `docs/<kind>/` (де `<kind>` — `specs` або `plans`) з пріоритезацією за хвостом (`slug`) гілки і вибором найсвіжішого файлу за `mtime`.
-2. **Екстракт нумерованих кроків** із секції `## Кроки` плану у структурований масив `{ task, acceptance }`.
-3. **Read-only перевірка цілісності ланцюга артефактів** через CLI `n-cursor trace` (без мутацій).
-
-Ключова інваріанта: модуль **не пише** front-matter лінків (`spec.plan`, `plan.spec`, `plan.flow`) — це робить агент згідно з контрактом, описаним у правилі `flow.mdc`. Тут лише **верифікація**, бо мутатор `trace link` свідомо не реалізовано.
-
-Файл є чистим ES-модулем (`.mjs`), не має побічних ефектів на рівні імпорту і експортує три іменовані функції.
-
-## Експорти / API
-
-| Експорт           | Тип        | Призначення                                                   |
-| ----------------- | ---------- | ------------------------------------------------------------- |
-| `resolveArtifact` | `function` | Знаходить актуальний markdown-артефакт у `docs/<kind>/`.      |
-| `extractSteps`    | `function` | Парсить нумерований список кроків із тексту плану.            |
-| `verifyTrace`     | `function` | Перевіряє цілісність ланцюга артефактів через runner `trace`. |
-
-Внутрішні (не експортовані) константи:
-
-| Ім'я              | Значення          | Призначення                                                            |
-| ----------------- | ----------------- | ---------------------------------------------------------------------- |
-| `ACCEPTANCE_MARK` | `'— acceptance:'` | Маркер критерію приймання в рядку кроку (порівняння case-insensitive). |
-| `DIGITS_RE`       | `/^\d+$/u`        | RegExp для перевірки, що префікс рядка перед `. ` є лише з цифр.       |
-
-## Функції
-
-### `resolveArtifact(cwd, kind, branch)`
-
-**Сигнатура**
-
-```js
-export function resolveArtifact(cwd, kind, branch)
-```
-
-**Параметри**
-
-| Ім'я     | Тип                     | Обов'язковий | Опис                                                                                                   |
-| -------- | ----------------------- | ------------ | ------------------------------------------------------------------------------------------------------ |
-| `cwd`    | `string`                | так          | Абсолютний шлях до кореня worktree.                                                                    |
-| `kind`   | `'specs' \| 'plans'`    | так          | Підкаталог усередині `docs/` (`docs/specs/` або `docs/plans/`).                                        |
-| `branch` | `string` (опціональний) | ні           | Назва гілки задачі (напр. `claude/flow-gate`). Використовується для пріоритезації за хвостом (`slug`). |
-
-**Повертає**
-
-`string | null` — абсолютний шлях до знайденого `.md`-файлу або `null`, якщо каталог `docs/<kind>/` відсутній чи в ньому немає markdown-файлів.
-
-**Алгоритм / поведінка**
-
-1. Збирає `dir = join(cwd, 'docs', kind)`.
-2. Якщо `dir` не існує — повертає `null`.
-3. Сканує `dir` і фільтрує лише файли з розширенням `.md`. Якщо їх немає — `null`.
-4. Обчислює `slug` як останній сегмент `branch` після `/` (`'claude/flow-gate' -> 'flow-gate'`). Якщо `branch` не задано — `slug = null`.
-5. Формує `matched` — підмножину файлів, чиї назви **містять `slug`** (через `String.prototype.includes`). Якщо `slug` відсутній — `matched = []`.
-6. Формує `pool`: якщо `matched.length > 0` — `pool = matched`; інакше `pool = md` (усі markdown-файли каталогу).
-7. Серед `pool` обирає **найсвіжіший за `mtimeMs`** (а при рівності `mtime` — за зростанням за іменем, тож `.at(-1)` поверне лексикографічно більше ім'я як tie-breaker).
-8. Повертає `join(dir, best.f)`.
-
-**Side effects**
-
-- **Тільки читання ФС**: `existsSync`, `readdirSync`, `statSync` із `node:fs`. Жодних записів.
-
-**Особливості / нюанси**
-
-- Сортування використовує `Array.prototype.toSorted` (іммутабельний варіант `sort`), тож вихідний `pool` не модифікується.
-- Документація у JSDoc наголошує: попередній «лексикографічний» вибір був **хибним** при кількох артефактах на одну дату — це виявлено dogfood'ом.
-- Якщо в `pool` лише один файл — `.at(-1)` поверне його.
-
-### `extractSteps(text)`
-
-**Сигнатура**
-
-```js
-export function extractSteps(text)
-```
-
-**Параметри**
-
-| Ім'я   | Тип      | Обов'язковий | Опис                                                                                                |
-| ------ | -------- | ------------ | --------------------------------------------------------------------------------------------------- |
-| `text` | `string` | так          | Повний вміст markdown-файлу плану (або довільний текст). Приводиться до рядка через `String(text)`. |
-
-**Повертає**
-
-`{ task: string, acceptance?: string }[]` — масив кроків у тому порядку, в якому вони зустрілися у вхідному тексті. Якщо нічого не знайдено — порожній масив.
-
-**Формат, який розпізнається**
-
-```
-N. <текст задачі> — acceptance: <критерій приймання>
-```
-
-де `N` — одне або більше десяткових цифр. Маркер `— acceptance:` розпізнається **case-insensitive** (через `toLowerCase`).
-
-Якщо рядок не починається з `<цифри>. `, він **ігнорується** (best-effort, без помилок).
-
-**Алгоритм / поведінка**
-
-1. Розбиває вхід на рядки за `\n`.
-2. Для кожного рядка обрізає пробіли (`trim`).
-3. Шукає першу появу `. ` (`dot = line.indexOf('. ')`). Якщо `dot <= 0` (немає крапки з пробілом або вона на самому початку) — рядок пропускається.
-4. Перевіряє, що префікс `line.slice(0, dot)` повністю складається з цифр (`DIGITS_RE`). Інакше — пропуск.
-5. Виокремлює `body = line.slice(dot + 2).trim()`.
-6. Шукає в `body.toLowerCase()` позицію маркера `ACCEPTANCE_MARK` (`'— acceptance:'`).
-7. Якщо маркера немає — додає `{ task: body }`.
-8. Якщо маркер є — ділить `body` на `task` (до маркера) і `acceptance` (після маркера), обрізає обидва і додає `{ task, acceptance }`.
-
-**Side effects**
-
-- Жодних. Чиста функція.
-
-**Особливості / нюанси**
-
-- Використано `indexOf` замість regex для уникнення **regex-backtracking**, що даватиме лінійну складність на довгих рядках.
-- Маркер `—` — це **em-dash** (U+2014), не звичайний дефіс. Це важливо для збігу.
-- Поле `acceptance` опціональне у вихідних об'єктах: відсутнє, якщо маркер не знайдено.
-- Нумерація кроків зчитується як префікс, але **не повертається** у результат: повертаються лише `task` і опціонально `acceptance`. Сам номер не використовується для впорядкування — порядок повністю визначається порядком появи в тексті.
-
-### `verifyTrace(cwd, runTrace)`
-
-**Сигнатура**
-
-```js
-export function verifyTrace(cwd, runTrace)
-```
-
-**Параметри**
-
-| Ім'я       | Тип                              | Обов'язковий | Опис                                                                                  |
-| ---------- | -------------------------------- | ------------ | ------------------------------------------------------------------------------------- |
-| `cwd`      | `string`                         | так          | Абсолютний шлях до кореня worktree, який передається у trace-runner.                  |
-| `runTrace` | `(cwd: string) => number` (опц.) | ні           | Кастомний runner trace, що повертає exit-code. Призначений для **ін'єкції у тестах**. |
-
-**Повертає**
-
-`boolean` — `true`, якщо exit-code runner-а дорівнює `0` (ланцюг цілісний); `false` — інакше (розрив ланцюга або помилка).
-
-**Алгоритм / поведінка**
-
-1. Якщо `runTrace` не передано — створюється дефолтний runner, який викликає `runTraceCli([], { cwd: c, log: () => {} })` з модуля `../trace.mjs`. Логування глушиться (`log: () => {}`), тож зовнішніх ефектів у stdout/stderr не буде.
-2. Виконує `run(cwd)` і повертає `=== 0`.
-
-**Side effects**
-
-- Викликає `runTraceCli` з `../trace.mjs`, який у звичайному режимі **читає** артефакти й їхні front-matter. Жодних мутацій не передбачено — функція декларується як «read-only сигнал».
-- При використанні `runTrace` ін'єкції — side effects цілком визначаються переданим runner-ом.
-
-**Особливості / нюанси**
-
-- Семантика exit-code узгоджена з CLI: `0` — OK, `1` (або інше ненульове) — розрив.
-- Аргументи для `runTraceCli` фіксовані: порожній масив `[]` (без додаткових прапорців).
-
-## Залежності
-
-### Зовнішні (Node.js core)
-
-- `node:fs`:
-  - `existsSync` — перевірка існування каталогу `docs/<kind>/`.
-  - `readdirSync` — лістинг файлів у каталозі.
-  - `statSync` — отримання `mtimeMs` для сортування.
-- `node:path`:
-  - `join` — побудова шляхів `docs/<kind>/<file>.md`.
-
-### Внутрішні (проєктні)
-
-- `../trace.mjs` → `runTraceCli` — CLI-runner перевірки цілісності trace-ланцюга. Викликається в `verifyTrace`.
-
-### Контракти / правила
-
-- `flow.mdc` — описує контракт лінкування front-matter (`spec.plan`/`plan.spec`/`plan.flow`), яке робить агент, а не цей модуль.
-- Структура каталогів `docs/specs/` і `docs/plans/` — конвенція «Пасивний Турнікет».
-
-## Потік виконання / Використання
-
-Модуль є **бібліотечним**: він не запускається самостійно, а імпортується іншими частинами dispatcher-pipeline (фази `spec`/`plan`).
-
-### Типовий сценарій 1 — резолв plan-артефакту і парсинг кроків
-
-```js
-import { resolveArtifact, extractSteps } from './artifact.mjs'
-import { readFileSync } from 'node:fs'
-
-const planPath = resolveArtifact(process.cwd(), 'plans', 'claude/flow-gate')
-if (!planPath) {
-  // немає docs/plans/ або файлів — фаза має зупинитись
-  return
-}
-
-const text = readFileSync(planPath, 'utf8')
-const steps = extractSteps(text)
-// steps: [{ task: '...', acceptance: '...' }, ...]
-```
-
-### Типовий сценарій 2 — read-only перевірка ланцюга перед мерджем
-
-```js
-import { verifyTrace } from './artifact.mjs'
-
-if (!verifyTrace(process.cwd())) {
-  // ланцюг spec ↔ plan ↔ flow має розрив — сигнал агенту
-}
-```
-
-### Типовий сценарій 3 — інверсія залежності у тестах
-
-```js
-import { verifyTrace } from './artifact.mjs'
-
-// підставляємо фейковий runner, щоб не викликати реальний CLI
-const ok = verifyTrace('/tmp/fake-cwd', () => 0)
-// ok === true
-```
-
-### Контекст у dispatcher-конвеєрі
-
-1. **Фаза `spec`**: викликає `resolveArtifact(cwd, 'specs', branch)` для пошуку специфікації.
-2. **Фаза `plan`**: викликає `resolveArtifact(cwd, 'plans', branch)`, читає файл, потім `extractSteps(text)` — і отримує перелік кроків, які виконуватиме наступна фаза.
-3. **Гейт цілісності**: перед переходом на наступну фазу — `verifyTrace(cwd)` як сигнал, чи зв'язки front-matter не порушені.
-
-## Rebuild Test
-
-За цією документацією можна **відновити поведінку** модуля без оригінального коду:
-
-- Модуль експортує **рівно три функції**: `resolveArtifact`, `extractSteps`, `verifyTrace`.
-- `resolveArtifact(cwd, kind, branch)` шукає `.md` у `docs/<kind>/`, віддає пріоритет файлам, чиє ім'я містить `slug = branch.split('/').pop()`, серед них (або серед усіх, якщо збігу нема) обирає найсвіжіший за `mtime`; повертає абсолютний шлях або `null`.
-- `extractSteps(text)` парсить рядки виду `N. task — acceptance: crit` (em-dash, маркер case-insensitive), повертає масив `{ task, acceptance? }` у порядку появи; невалідні рядки ігноруються.
-- `verifyTrace(cwd, runTrace?)` повертає `true`, якщо `runTrace(cwd) === 0`; за замовчуванням викликає `runTraceCli([], { cwd, log: () => {} })` з `../trace.mjs`.
-- Жодних мутацій ФС, жодного запису front-matter — це робить агент за `flow.mdc`.

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

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

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

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