@nitra/cursor 4.1.2 → 5.0.1

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

@@ -1,231 +0,0 @@
-# `gate.mjs` — реалізація команди `flow gate`
-
-## Огляд
-
-Модуль реалізує підкоманду `flow gate` диспатчера — структурований вердикт релізної готовності у стилі BMAD `qa-gate`, адаптованого до внутрішнього флоу проєкту. Скрипт **синтезує** два джерела сигналів, що накопичуються у файлі стану флоу (`.flow.json`):
-
-1. Механічні гейти, які заповнює крок `verify` (`state.gates` — масив `{ name, ok }`).
-2. Adversarial-зауваження, які залишає крок `review` (`state.review.findings` — масив об'єктів із полем `severity`).
-
-На виході формується єдиний вердикт `PASS | CONCERNS | FAIL`, числовий `score` у діапазоні `0..100` та список людиночитаних причин. Командa `gate` **не приймає рішень** за `verify` чи `review`, а лише агрегує їх — це забезпечує traceability «чому готово / не готово».
-
-Архітектурно модуль складається з двох частин:
-
-- `computeGate(state)` — **чиста** функція, повністю детермінована від вхідного стану, не торкається диска й часу. Призначена для unit-тестів без I/O-моків.
-- `gate(_rest, deps)` — async-обгортка, що читає стан з диска, викликає `computeGate`, фіксує результат як подію в `events.jsonl` і повертає exit-код для CLI. Усі залежності IO (`cwd`, `log`, `now`) ін'єктуються через `deps`, що робить функцію тестопридатною.
-
-## Експорти / API
-
-| Експорт       | Тип              | Призначення                             |
-| ------------- | ---------------- | --------------------------------------- |
-| `computeGate` | `function`       | Чистий синтез вердикту з об'єкта стану. |
-| `gate`        | `async function` | CLI-handler підкоманди `flow gate`.     |
-
-Модуль не має default-експорту. Внутрішня константа `PENALTY` (штрафи score) **не експортується** і є приватною деталлю реалізації.
-
-### `computeGate(state)`
-
-Сигнатура (JSDoc):
-
-```
-@param  {{ gates?: { name: string, ok: boolean }[],
-            review?: { findings?: { severity?: string }[] } }} state
-@returns {{ verdict: 'PASS' | 'CONCERNS' | 'FAIL',
-             score: number,
-             reasons: string[] }}
-```
-
-### `gate(_rest, deps)`
-
-Сигнатура (JSDoc):
-
-```
-@param  {string[]} _rest             аргументи CLI (не використовуються)
-@param  {{ cwd?: string,
-            log?: (m: string) => void,
-            now?: () => number,
-            branch?: string }}  [deps]  ін'єкції
-@returns {Promise<number>}            exit-код (FAIL → 1; PASS/CONCERNS → 0)
-```
-
-Параметр `_rest` зберігається в сигнатурі для уніфікації з рештою CLI-handlers диспатчера; підкреслення на початку позначає навмисне ігнорування. Крім задокументованих у JSDoc полів `deps`, реалізація читає також `deps.branch` — він передається в `resolveActiveFlowState`.
-
-## Функції
-
-### `computeGate(state)`
-
-- **Сигнатура:** `computeGate(state) → { verdict, score, reasons }`.
-- **Параметри:**
-  - `state.gates` (необов'язково) — масив об'єктів `{ name: string, ok: boolean }`. Якщо відсутній, береться `[]`.
-  - `state.review.findings` (необов'язково) — масив об'єктів із полем `severity` зі значенням `'high'` або `'med'` (інші значення ігноруються при підрахунку штрафів). Якщо відсутній — `[]`.
-- **Повертає:** об'єкт `{ verdict, score, reasons }`.
-  - `verdict` — рядок `'PASS'`, `'CONCERNS'` або `'FAIL'`.
-  - `score` — ціле число `0..100`, обмежене через `Math.max(0, Math.min(100, …))`.
-  - `reasons` — масив рядкових пояснень (можливо порожній при `PASS`).
-- **Side effects:** немає. Функція чиста, детермінована, без I/O і без використання глобального часу.
-
-**Алгоритм синтезу:**
-
-1. Розбиває `gates` на `failedGates = gates.filter(g => !g.ok)`.
-2. Розбиває `findings` на дві групи за `severity`: `high` і `med`.
-3. Прапор `noVerify = gates.length === 0` — стан, коли `verify` ще не запускався.
-4. Формує `reasons`:
-   - для кожного провального гейта: `gate «<name>» провалено`;
-   - якщо `high.length > 0`: `<N> high-severity review finding(s)`;
-   - якщо `med.length > 0`: `<N> med-severity review finding(s)`;
-   - якщо `noVerify`: `verify ще не запускався`.
-5. Визначає `verdict` за пріоритетом:
-   - `FAIL` — якщо є хоча б один провальний гейт **або** хоча б один `high`-finding;
-   - інакше `CONCERNS` — якщо є `med`-findings **або** `noVerify`;
-   - інакше `PASS`.
-6. Обраховує `penalty` як суму штрафів `PENALTY`:
-   - `failedGate = 40` за кожен провальний гейт;
-   - `high = 25` за кожен `high`-finding;
-   - `med = 8` за кожен `med`-finding;
-   - `noVerify = 15` (одноразово, якщо `gates` порожній).
-7. `score = max(0, min(100, 100 - penalty))`.
-
-**Інваріанти:**
-
-- `FAIL` ⇒ `score < 100` (`penalty ≥ 25` гарантовано через high або failedGate ≥ 40).
-- `PASS` ⇒ `penalty = 0` ⇒ `score = 100`.
-- `CONCERNS` досяжний при `penalty > 0` без `failedGates` і без `high`.
-- `score` ніколи не виходить за `[0, 100]`.
-
-### `gate(_rest, deps = {})`
-
-- **Сигнатура:** `async gate(_rest, deps) → Promise<number>`.
-- **Параметри:**
-  - `_rest` — масив рядків (CLI-аргументи), ігнорується.
-  - `deps.cwd` — поточна робоча директорія; default — `process.cwd()`.
-  - `deps.log` — функція логування; default — `console.error`.
-  - `deps.now` — провайдер часу `() => number`; default — `Date.now`.
-  - `deps.branch` — додаткова підказка для `resolveActiveFlowState` (необов'язково).
-- **Повертає:** `Promise<number>` — exit-код процесу:
-  - `1` — якщо стан недоступний (немає активного флоу або `flow init` ще не виконувався) або вердикт `FAIL`;
-  - `0` — для `PASS` і `CONCERNS`.
-- **Side effects:**
-  - Викликає `resolveActiveFlowState` (може читати worktree/гілку).
-  - Викликає `readState(statePath)` — синхронне читання `.flow.json`.
-  - Викликає `recordTransition(...)` — мутація `.flow.json` і дописування в `events.jsonl` (через `flowEventsPath(cwd)`).
-  - Логування в `deps.log` (за замовчуванням stderr).
-
-**Покроковий потік:**
-
-1. Розв'язує дефолтні залежності: `cwd0`, `log`, `now`.
-2. `resolveActiveFlowState({ cwd: cwd0, branch })` визначає активний флоу:
-   - якщо `resolved.statePath` пустий — логує `gate: <error>` і повертає `1`;
-   - якщо `resolved.autoResolved` — логує повідомлення `flow: авторезолвлено активний flow «<label>» (cwd поза worktree)`.
-3. Підставляє `cwd = resolved.worktreeDir ?? cwd0` і `statePath = resolved.statePath`.
-4. Читає стан `readState(statePath)`; якщо `null/undefined` — логує `gate: стану нема — спершу `flow init``і повертає`1`.
-5. Викликає `computeGate(state)` → `result`.
-6. Викликає `recordTransition` з:
-   - шляхами `{ statePath, eventsPath: flowEventsPath(cwd) }`,
-   - подією `{ type: 'gate', verdict: result.verdict }`,
-   - редьюсером `s => ({ ...s, gate: { ...result, at: new Date(now()).toISOString() } })` — додає до стану секцію `gate` з `verdict`/`score`/`reasons`/`at` (ISO-таймстемп);
-   - провайдером часу `now`.
-7. Логує рядок `gate: <VERDICT> (score <N>)`, потім по `  · <reason>` для кожної причини.
-8. Повертає `1`, якщо `result.verdict === 'FAIL'`, інакше `0`.
-
-## Залежності
-
-### Зовнішні (Node.js core)
-
-- `node:process` — імпорт `cwd as processCwd` для дефолтного значення `deps.cwd`.
-
-### Внутрішні модулі диспатчера
-
-- `./events.mjs` — функція `flowEventsPath(cwd)` будує шлях до файлу подій `events.jsonl` поточного флоу.
-- `./state-store.mjs`:
-  - `readState(statePath)` — синхронне читання `.flow.json` (повертає `null`, якщо нема);
-  - `recordTransition({ statePath, eventsPath }, event, reducer, now)` — атомарна мутація стану + лог подій.
-- `./flow-resolve.mjs` — `resolveActiveFlowState({ cwd, branch }, deps)` визначає активний worktree/гілку/`statePath`; повертає поля `statePath`, `worktreeDir`, `autoResolved`, `label`, `error`.
-
-### Глобальні
-
-- `console.error` — дефолтний логер (замінюється через `deps.log` у тестах).
-- `Date.now`, `new Date(...).toISOString()` — джерело таймстемпів (час ін'єктується через `deps.now`, але `new Date(...).toISOString()` працює з результатом).
-
-## Потік виконання / Використання
-
-### Інтеграція в CLI
-
-`gate` реєструється в основному диспатчері `flow` як handler підкоманди `gate`. Виклик відбувається у форматі:
-
-```
-flow gate
-```
-
-Додаткові позиційні аргументи не зчитуються (`_rest` ігнорується).
-
-### Типовий ланцюжок флоу
-
-```
-flow init      → створює .flow.json
-flow verify    → заповнює state.gates
-flow review    → заповнює state.review.findings
-flow gate      → агрегує → state.gate = { verdict, score, reasons, at }
-```
-
-### Сценарії exit-коду
-
-| Сценарій                  | Лог                                     | Exit |
-| ------------------------- | --------------------------------------- | ---- |
-| Активний флоу не знайдено | `gate: <error>`                         | `1`  |
-| `.flow.json` відсутній    | `gate: стану нема — спершу `flow init`` | `1`  |
-| `verdict = FAIL`          | `gate: FAIL (score …)` + причини        | `1`  |
-| `verdict = CONCERNS`      | `gate: CONCERNS (score …)` + причини    | `0`  |
-| `verdict = PASS`          | `gate: PASS (score 100)`                | `0`  |
-
-### Приклад чистого використання `computeGate`
-
-```js
-import { computeGate } from './gate.mjs'
-
-const state = {
-  gates: [
-    { name: 'lint', ok: true },
-    { name: 'test', ok: false }
-  ],
-  review: { findings: [{ severity: 'med' }] }
-}
-
-computeGate(state)
-// → { verdict: 'FAIL', score: 52, reasons: [
-//     'gate «test» провалено',
-//     '1 med-severity review finding(s)'
-//   ] }
-```
-
-### Приклад тестування `gate` через ін'єкції
-
-```js
-import { gate } from './gate.mjs'
-
-const logs = []
-const code = await gate([], {
-  cwd: '/tmp/fixture',
-  log: m => logs.push(m),
-  now: () => 1_700_000_000_000
-})
-
-// code === 0 | 1
-// logs містить рядки виду 'gate: PASS (score 100)' / '  · …'
-```
-
-### Записи в `.flow.json`
-
-Після успішного виконання у стані з'являється секція:
-
-```json
-{
-  "gate": {
-    "verdict": "CONCERNS",
-    "score": 92,
-    "reasons": ["1 med-severity review finding(s)"],
-    "at": "2024-01-01T00:00:00.000Z"
-  }
-}
-```
-
-Подія `{ type: 'gate', verdict }` дописується в `events.jsonl` через `recordTransition`.

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

@@ -1,335 +0,0 @@
-# level.mjs
-
-## Огляд
-
-Модуль `level.mjs` реалізує **scale-adaptive детекцію рівня складності й рівня ризику** задачі за її текстовим описом. Ідея запозичена з BMAD (project-levels / risk-profile) і адаптована до внутрішніх термінів проєкту.
-
-Призначення модуля у контексті dispatcher:
-
-- На етапі `init` (ініціалізація задачі/флоу) функція виклику аналізує текстовий опис задачі і відносить її до одного з чотирьох рівнів складності `L0..L3` та одного з трьох рівнів ризику `low | med | high`.
-- Поєднання `level` + `risk` _right-size_-ить (масштабує) подальший пайплайн: зокрема, скільки adversarial-рецензентів спавнить команда `flow review` і яка її глибина/фокус, а також які фази робочого процесу рекомендовані як контракт.
-- Усі рішення детермінуються пошуком ключових слів у нижньому регістрі без використання регулярних виразів — це свідомий вибір для уникнення slow-regex та проблем зі словесними межами для кириличних символів.
-
-Файл є **чистою бібліотекою без побічних ефектів**: не звертається до файлової системи, мережі, не пише в `stdout/stderr`, не залежить від часу. Усі експорти — детерміновані функції від рядкового опису (або числа/рядка).
-
-## Експорти / API
-
-Модуль експортує чотири іменовані функції (усі — `export function`):
-
-| Експорт             | Сигнатура                                    | Призначення                                                                 |
-| ------------------- | -------------------------------------------- | --------------------------------------------------------------------------- |
-| `detectLevel`       | `(desc: string) => 0 \| 1 \| 2 \| 3`         | Визначає рівень складності задачі за описом.                                |
-| `reviewersForLevel` | `(level: number) => number`                  | Кількість adversarial-рецензентів на основі рівня (1..3).                   |
-| `detectRisk`        | `(desc: string) => 'low' \| 'med' \| 'high'` | Визначає рівень ризику задачі за описом.                                    |
-| `reviewersForRisk`  | `(risk: string) => number`                   | Кількість рецензентів на основі ризику (1..3).                              |
-| `reviewersFor`      | `(level: number, risk?: string) => number`   | Підсумкова кількість рецензентів: максимум вимог рівня й ризику, з капом 3. |
-
-Внутрішні (НЕ експортовані) допоміжні функції: `isAsciiAlnum`, `hasWord`.
-
-Внутрішні константи з наборами ключових слів: `L3_KEYS`, `L0_WORD_KEYS`, `L0_SUBSTR_KEYS`, `L2_KEYS`, `HIGH_RISK_KEYS`, `MED_RISK_KEYS`.
-
-## Константи (внутрішні)
-
-### `L3_KEYS`
-
-Ключові слова, що сигналізують про **архітектурні/великі/міграційні** задачі (рівень L3).
-
-```text
-['platform', 'migration', 'rewrite', 'architecture', 'enterprise',
- 'редизайн', 'міграц', 'переписат']
-```
-
-Збігаються звичайним `indexOf` (підрядок, case-insensitive після приведення опису до lowercase). Кириличні корені `міграц` / `переписат` спеціально вкорочені до основи слова (стемінг), щоб ловити будь-які закінчення (`міграція`, `міграційний`, `переписати`, `переписану`).
-
-### `L0_WORD_KEYS`
-
-ASCII-дієслова, що сигналізують про **тривіальні** задачі (рівень L0). Матчаться **тільки як ціле слово** через `hasWord` — щоб `fix` не ловило `prefix` / `fixture`.
-
-```text
-['fix', 'typo', 'bump', 'rename', 'hotfix']
-```
-
-### `L0_SUBSTR_KEYS`
-
-Кириличні ключі для L0, матчаться **підрядком** (стемінг: `перейменув` ловить `перейменування`, `перейменувати` тощо).
-
-```text
-['опечат', 'перейменув']
-```
-
-### `L2_KEYS`
-
-Ключові слова для **багатофайлових фіч/рефакторів** (рівень L2). Матчаться підрядком.
-
-```text
-['feature', 'epic', 'refactor', 'рефактор', 'фіча']
-```
-
-### `HIGH_RISK_KEYS`
-
-Ключі **високого** ризику (безпека, гроші, доступи). Матчаються підрядком.
-
-```text
-['security', 'auth', 'crypto', 'payment', 'secret', 'token',
- 'permission', 'password', 'безпек']
-```
-
-### `MED_RISK_KEYS`
-
-Ключі **середнього** ризику (дані, незворотність). Матчаться підрядком.
-
-```text
-['data', ' db', 'database', 'migration', 'delete', 'gateway',
- 'міграц', 'видален']
-```
-
-Зверніть увагу: ключ `' db'` навмисно записаний з провідним пробілом — це дешевий спосіб відрізнити окреме слово `db` від випадкових підрядків (наприклад, у `dbg`, `dbus`), не вдаючись до пошуку зі словесними межами.
-
-## Функції
-
-### `isAsciiAlnum(ch)` _(internal)_
-
-**Сигнатура:** `function isAsciiAlnum(ch: string | undefined): boolean`
-
-**Параметри:**
-
-- `ch` — один символ (або `undefined`, що моделює "край рядка" перед нульовою позицією чи за останньою).
-
-**Повертає:** `true`, якщо `ch` — ASCII-літера в нижньому регістрі (`a..z`) або ASCII-цифра (`0..9`). Інакше `false`. Для `undefined` повертає `false` (край рядка не вважається символом alnum).
-
-**Side effects:** немає.
-
-**Використання:** як перевірка межі слова в `hasWord`. Свідомо охоплює лише lowercase ASCII (бо вхід вже зведено до `.toLowerCase()` у `detectLevel`/`detectRisk`).
-
-### `hasWord(text, word)` _(internal)_
-
-**Сигнатура:** `function hasWord(text: string, word: string): boolean`
-
-**Параметри:**
-
-- `text` — основний текст (передбачається lowercase після `.toLowerCase()`).
-- `word` — шукане ASCII-слово (lowercase).
-
-**Повертає:** `true`, якщо в `text` зустрічається `word` і обидві його межі (символ безпосередньо до й безпосередньо після) **не є** ASCII-alnum (тобто це справді ціле слово); інакше `false`.
-
-**Алгоритм:**
-
-1. Шукає перше входження `word` через `text.indexOf(word)`.
-2. Поки знайдено (`i !== -1`):
-   - Перевіряє ліву межу: `text[i - 1]` (або `undefined`, якщо `i === 0`).
-   - Перевіряє праву межу: `text[i + word.length]` (або `undefined`, якщо це кінець рядка).
-   - Якщо **жодна** з них не є ASCII-alnum — повертає `true`.
-   - Інакше шукає наступне входження через `text.indexOf(word, i + 1)`.
-3. Якщо всі входження виявилися підрядками всередині більших слів — повертає `false`.
-
-**Side effects:** немає.
-
-**Чому без regex:** конвенція файлу — уникати `RegExp` для запобігання slow-regex атакам і неоднозначностям `\b` на кириличних межах слів (де `\b` в JS-regex поводиться непередбачувано). Ручний прохід через `indexOf` дешевший і явніший.
-
-### `detectLevel(desc)`
-
-**Експорт:** `export function detectLevel(desc): 0 | 1 | 2 | 3`
-
-**Параметри:**
-
-- `desc` — опис задачі (будь-який тип; усередині нормалізується через `String(desc ?? '')`).
-
-**Повертає:** один із літералів `0 | 1 | 2 | 3` — рівень складності.
-
-**Side effects:** немає.
-
-**Алгоритм (з пріоритетом L3 > L0 > L2 > L1):**
-
-1. Нормалізує `desc` до рядка: `String(desc ?? '')` (значення `null`/`undefined` стають порожнім рядком).
-2. Зводить рядок у нижній регістр: `const d = ...toLowerCase()`.
-3. Створює локальний хелпер `has = keys => keys.some(k => d.includes(k))` (підрядковий пошук).
-4. Обчислює `isL0`:
-   - `L0_WORD_KEYS.some(k => hasWord(d, k))` — ASCII-дієслова як ціле слово, **АБО**
-   - `L0_SUBSTR_KEYS.some(k => d.includes(k))` — кириличні підрядки.
-5. Послідовно перевіряє:
-   - Якщо `has(L3_KEYS)` → `3`.
-   - Інакше якщо `isL0` → `0`.
-   - Інакше якщо `has(L2_KEYS)` → `2`.
-   - Інакше → дефолт `1`.
-
-**Семантика пріоритетів:**
-
-- L3 виграє у всіх: навіть якщо опис містить і `migration`, і `fix`, рівень буде `3` — велика міграція важливіша за згадку дрібного фіксу.
-- L0 наступний: тривіальні зміни не повинні маскуватися під L2-фічу через випадковий збіг.
-- L2 — middle ground для багатофайлових задач.
-- L1 — дефолт, коли жоден сигнал не зловлено.
-
-**Приклади:**
-
-- `'Fix typo in README'` → L0 (`fix` як слово; `typo`).
-- `'Add database migration for users'` → L3 (через `migration`, що в L3_KEYS).
-- `'Refactor auth module'` → L2 (`refactor`; `auth` тут не змінює рівень — це сигнал ризику, не рівня).
-- `'Update copy on landing'` → L1 (нічого не зловлено).
-- `'Prefix new fields with role_'` → L1 (`prefix` НЕ ловиться L0_WORD_KEYS через цілословний матч `fix`).
-
-### `reviewersForLevel(level)`
-
-**Експорт:** `export function reviewersForLevel(level: number): number`
-
-**Параметри:**
-
-- `level` — числовий рівень (зазвичай `0..3`, але приймає будь-яке число).
-
-**Повертає:** ціле в діапазоні `1..3` — рекомендована кількість adversarial-рецензентів суто на основі рівня.
-
-**Side effects:** немає.
-
-**Таблиця рішень:**
-
-| `level`                    | Повертає |
-| -------------------------- | -------- |
-| `>= 3`                     | `3`      |
-| `=== 2`                    | `2`      |
-| решта (`0`, `1`, від'ємні) | `1`      |
-
-**Семантика:** глибина review корелює з масштабом задачі.
-
-### `detectRisk(desc)`
-
-**Експорт:** `export function detectRisk(desc): 'low' | 'med' | 'high'`
-
-**Параметри:**
-
-- `desc` — опис задачі (будь-який тип; усередині нормалізується через `String(desc ?? '')`).
-
-**Повертає:** літерал `'low' | 'med' | 'high'`.
-
-**Side effects:** немає.
-
-**Алгоритм:**
-
-1. Нормалізує: `const d = String(desc ?? '').toLowerCase()`.
-2. `has = keys => keys.some(k => d.includes(k))` — суто підрядковий пошук (для ризику немає різниці ASCII vs кирилиця: всі ключі матчаться як підрядки).
-3. Якщо `has(HIGH_RISK_KEYS)` → `'high'`.
-4. Інакше якщо `has(MED_RISK_KEYS)` → `'med'`.
-5. Інакше → `'low'`.
-
-**Семантика пріоритетів:** `high > med > low`. Якщо опис одночасно містить і high-, і med-сигнал — виграє `high`.
-
-**Приклади:**
-
-- `'Add password reset flow'` → `'high'` (`password`).
-- `'Migrate user data to new schema'` → `'high'` (`migration`/`міграц` — НІ, але `data` в MED_RISK_KEYS… насправді тут `migration` теж у MED_RISK_KEYS, а high-ключів немає → `'med'`).
-- `'Bump dep version'` → `'low'`.
-
-### `reviewersForRisk(risk)`
-
-**Експорт:** `export function reviewersForRisk(risk: string): number`
-
-**Параметри:**
-
-- `risk` — рядок (очікувано `'low' | 'med' | 'high'`; інші значення трактуються як low).
-
-**Повертає:** ціле `1..3` — рекомендована кількість рецензентів суто за ризиком.
-
-**Side effects:** немає.
-
-**Таблиця рішень:**
-
-| `risk`                                                | Повертає |
-| ----------------------------------------------------- | -------- |
-| `'high'`                                              | `3`      |
-| `'med'`                                               | `2`      |
-| решта (включно з `'low'`, `undefined`, неочікуваними) | `1`      |
-
-### `reviewersFor(level, risk)`
-
-**Експорт:** `export function reviewersFor(level: number, risk?: string): number`
-
-**Параметри:**
-
-- `level` — числовий рівень складності (`0..3`).
-- `risk` — необов'язковий рядок ризику (`'low' | 'med' | 'high'`).
-
-**Повертає:** ціле `1..3` — підсумкова кількість рецензентів, **максимум** вимог за рівнем і за ризиком, з верхнім капом `3`.
-
-**Side effects:** немає.
-
-**Формула:**
-
-```text
-Math.min(3, Math.max(reviewersForLevel(level), reviewersForRisk(risk)))
-```
-
-**Семантика:**
-
-- Високий ризик піднімає глибину review навіть для L0/L1.
-- Велика задача (L3) гарантує максимум рецензентів незалежно від ризику.
-- Кап `3` страхує від екзотичних вхідних значень `level > 3` (не виходимо за межі узгодженого діапазону).
-
-**Приклади (level, risk → reviewers):**
-
-| `level` | `risk`      | Результат       |
-| ------- | ----------- | --------------- |
-| `0`     | `'low'`     | `max(1, 1) = 1` |
-| `0`     | `'high'`    | `max(1, 3) = 3` |
-| `2`     | `'low'`     | `max(2, 1) = 2` |
-| `3`     | `'med'`     | `max(3, 2) = 3` |
-| `1`     | `undefined` | `max(1, 1) = 1` |
-
-## Залежності
-
-**Зовнішні (npm/Node.js):** немає. Файл повністю самодостатній.
-
-**Стандартні API:** використовує лише вбудовані операції рядка (`String`, `toLowerCase`, `indexOf`, доступ за індексом, `length`) та `Math.min` / `Math.max`.
-
-**Внутрішні (з інших модулів проєкту):** немає `import`/`require`.
-
-**Хто залежить від цього модуля:** очікувано — модулі команди `init` (ініціалізація флоу) та `flow review` (вибір кількості рецензентів). Інші частини dispatcher можуть викликати `reviewersFor` як єдину точку входу для розрахунку review-глибини.
-
-## Потік виконання / Використання
-
-Типовий потік:
-
-1. **Ініціалізація задачі (`init`).** Викликач має текстовий опис задачі (наприклад, з ADR-чернетки або з CLI-аргументу). Імпортує `detectLevel` і `detectRisk`:
-
-   ```js
-   import { detectLevel, detectRisk, reviewersFor } from './level.mjs'
-
-   const level = detectLevel(taskDescription) // 0 | 1 | 2 | 3
-   const risk = detectRisk(taskDescription) // 'low' | 'med' | 'high'
-   ```
-
-2. **Запис у стан флоу.** Значення `level` і `risk` зберігаються у стейті задачі (state-store / spec / артефакти), щоб бути доступними наступним командам.
-
-3. **Розрахунок глибини review (`flow review`).** Перед спавном adversarial-рецензентів викликається `reviewersFor`:
-
-   ```js
-   import { reviewersFor } from './level.mjs'
-
-   const reviewers = reviewersFor(level, risk) // 1..3
-   for (let i = 0; i < reviewers; i++) {
-     spawnAdversarialReviewer({ index: i, level, risk })
-   }
-   ```
-
-4. **Рекомендовані фази (контракт).** Рівень і ризик також впливають на те, які фази робочого процесу обов'язкові (наприклад, для L3/high — повний цикл з планом, ревью, gate; для L0/low — спрощений шлях). Це використання вже виходить за межі цього файлу, але `detectLevel` + `detectRisk` — точка входу для таких рішень.
-
-**Інваріанти й гарантії:**
-
-- Усі функції чисті й детерміновані: однаковий вхід → однаковий вихід.
-- `detectLevel` / `detectRisk` стійкі до `null` / `undefined` / нерядкових входів (приведення через `String(x ?? '')`).
-- Жодна функція не кидає виключень для типових входів.
-- Жодна функція не виконує I/O.
-
-**Обмеження детекції:**
-
-- Простий пошук підрядків може давати false-positive на природній мові (наприклад, фраза "no migration needed" все одно тригерить L3). Це свідомий компроміс на користь швидкості і детермінізму.
-- ASCII-дієслова L0 потребують матчу цілим словом; кириличні L0 матчаться підрядком — це асиметрія, продиктована особливостями токенізації двох алфавітів.
-
-## Rebuild Test
-
-Документація достатня для відтворення модуля з нуля без перегляду оригіналу:
-
-- Усі експорти, їхні сигнатури, параметри, тип повертального значення й семантика описані.
-- Внутрішні константи (списки ключових слів) наведені дослівно, з поясненням, чому окремі ключі сформовані саме так (стемінг, провідний пробіл у `' db'`).
-- Алгоритми `detectLevel` / `detectRisk` / `hasWord` / `isAsciiAlnum` описані покроково з порядком пріоритетів і дефолтами.
-- Формула `reviewersFor` з капом і максимумом наведена явно.
-- Зафіксовано принципову відмову від regex з обґрунтуванням.
-
-За цією специфікацією модуль `level.mjs` можна повністю відтворити, і його поведінка на типових входах буде ідентичною оригіналу.