@nitra/cursor 12.3.0 → 12.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [12.3.2] - 2026-06-20
+
+### Fixed
+
+- fix-каскад: per-tier timeout (локалі fail-fast ~45s замість стіни 120s, env N_LOCAL_FIX_TIMEOUT_MS/N_CLOUD_FIX_TIMEOUT_MS) + хмарний транспортний збій (pi ETIMEDOUT/spawn) обриває драбину замість ескалації на cloud-avg — не палиться avg-бюджет
+
+## [12.3.1] - 2026-06-20
+
+### Changed
+
+- npm-module конформність: module-level JSDoc → pointer (`/** @see ./docs/… */`) у docgen-crc/extract-anchors/files-batch/judge-measure, doc-files/lint, lint/orchestrate, doc-aggregate/docgen-ignore; doc-CRC перештамповано; eslint --fix-стан прийнято як канон
+
 ## [12.3.0] - 2026-06-19
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.3.0",
+  "version": "12.3.2",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -68,4 +68,4 @@
     "skills": "skills",
     "extensions": ".pi-template/extensions"
   }
-}
+}

package/rules/doc-files/js/docgen-crc.mjs

@@ -1,34 +1,4 @@
-/**
- * CRC32 джерела + YAML-frontmatter файлової документації.
- *
- * Кожна файлова дока несе у frontmatter контрольну суму байтів джерела на момент
- * генерації. Це детермінований маркер застарілості: `crc32(поточне джерело)` звіряється
- * з `crc` у доці — розбіжність (або відсутня дока) означає, що дока відстала від коду.
- * CRC не залежить від git-стану (rebase, незакомічене, гілки), тож придатний і для
- * per-edit hook (бачить лише змінений файл), і для повного сканування.
- *
- * Degraded-маркер (ADR 260610-2228): якщо локальний конвеєр не дотягнув до порогу
- * якості, дока все одно пишеться, а frontmatter додатково несе `score` (det-оцінка)
- * та `issues` (коди проблем). CRC при цьому свіжий — Stop-гейт не блокує задачі через
- * слабкість моделі; борг видимий через `check --degraded` і автоматично доретраюється
- * наступним `gen` (рівно один раз на версію джерела — далі `retried: true` у frontmatter).
- *
- * Frontmatter — єдиний дозволений виняток із правила «чистий Markdown без HTML»:
- * це машинні метадані, не контент. Формат:
- *
- *   ---
- *   docgen:
- *     source: src/lib/foo.js
- *     crc: a3f1c9e0
- *     model: omlx/gemma-4-e4b-it-OptiQ-4bit
- *     score: 55
- *     issues: short-behavior,internal-name:bar
- *   ---
- *
- * `model` — повний id моделі-генератора (як повертає resolveModel, із префіксом
- * провайдера). Пасивна метадата: маркер «віку» доки за моделлю на додачу до CRC
- * джерела. На staleness НЕ впливає — звіряється лише `crc`.
- */
+/** @see ./docs/docgen-crc.md */
 import { existsSync, readFileSync } from 'node:fs'
 import { basename, extname } from 'node:path'
 import { crc32 as zlibCrc32 } from 'node:zlib'
@@ -173,6 +143,9 @@ export function buildDocFrontmatter(source, crc, quality = null, model = null) {
  */
 const LEADING_H1_RE = /^#[^\n]*\n+/u
 
+/**
+ *
+ */
 export function stampDoc(md, source, crc, quality = null, model = null) {
   const { body } = parseDocFrontmatter(md)
   const cleanBody = body.replace(LEADING_NEWLINES_RE, '').replace(LEADING_H1_RE, '')

package/rules/doc-files/js/docgen-extract-anchors.mjs

@@ -1,18 +1,4 @@
-/**
- * E1 (Fact-anchoring): детермінований витяг «анкорів» — конкретних фрагментів
- * з коду, які LLM зобовʼязана згадати в документації, щоб не зісковзнути на
- * generic-фрази.
- *
- * Категорії анкорів:
- *   - urls         : усі https?://… у вихідному коді
- *   - magicStrings : export const X = '…' з непорожнім value (≤120 символів)
- *   - errorMarkers : суфікси повідомлень про помилки виду `(rule.mdc)`
- *   - configRefs   : посилання на .json-конфіги проєкту (.n-cursor.json, …)
- *   - examples     : ```…```-блоки у file-header JSDoc (першому коментарі файла)
- *
- * Всі регулярки — на сирому src без AST: дешево, безпечно, без false-positive
- * критичної ваги (надмір — менша проблема, ніж пропуск).
- */
+/** @see ./docs/docgen-extract-anchors.md */
 
 const URL_RE = /https?:\/\/[^\s'"`)<>]+/g
 // Після обрізання template-частини URL має лишитися host (R10).

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -1,15 +1,4 @@
-/**
- * JS-оркестрація генерації файлових док (local-only, ADR 260610-2228).
- *
- * Уся черга/батчинг/CRC-штамп живуть тут, а не в контексті моделі — тому
- * масовий перший прогін на сотні файлів не «заморює» агента. Конвеєр суто
- * локальний: жодних cloud-ескалацій; якщо det-score нижче порогу — дока все
- * одно пишеться з degraded-маркером (`score`/`issues` у frontmatter), а наступний
- * `gen` автоматично доретраює такі доки (один раз на версію джерела — далі `retried:true`).
- *
- * Перед масовим прогоном — health-check omlx: memory-guard зайнятої 8GB машини
- * означає «відклади прогін», а не сотні хибних «✗» у звіті.
- */
+/** @see ./docs/docgen-files-batch.md */
 import { readFileSync, readdirSync, mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs'
 import { basename, dirname, join, relative } from 'node:path'
 

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -1,21 +1,4 @@
-#!/usr/bin/env node
-/**
- * docgen-judge-measure.mjs — Q4 офлайн-вимірювач (spec 2026-06-14-docgen-judge-design).
- *
- * Міряє false-positive rate детермінованого `scoreDoc`: серед доків, що ПРОЙШЛИ
- * (score ≥ threshold), який % сильна хмарна модель-суддя класифікує як
- * `generic`/`inaccurate`. Це число вирішує, чи будувати рантайм-judge-гейт.
- *
- * Генерація: локальна (N_LOCAL_MIN_MODEL, omlx/* → прямий HTTP) — реальний пайплайн.
- * Суддя: openai-codex/gpt-5.4-mini (сильніша хмара, ніж генератор — інакше вимір беззмістовний).
- * Обидва — через існуючий `../../../lib/llm.mjs callLlm` (маршрутизація за префіксом).
- *
- * Кеш на диску (за хешем контенту) → повторні прогони не регенерують і не пересуджують.
- *
- * Usage:
- *   node docgen-judge-measure.mjs <file1> <file2> ...
- *   MEASURE_CACHE=/tmp/x N_CLOUD_MIN_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
- */
+/** @see ./docs/docgen-judge-measure.md */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
 import { join } from 'node:path'
@@ -39,10 +22,16 @@ Prefer "inaccurate" over "generic" if any claim is wrong. Respond with ONLY a JS
 
 const sha = s => createHash('sha256').update(s).digest('hex').slice(0, 16)
 
+/**
+ *
+ */
 function cacheGet(key) {
   const p = join(CACHE_DIR, key + '.json')
   return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null
 }
+/**
+ *
+ */
 function cacheSet(key, val) {
   if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
   writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
@@ -83,6 +72,9 @@ function judgeCached(src, doc) {
   return { ...v, cached: false }
 }
 
+/**
+ *
+ */
 function main() {
   const files = process.argv.slice(2).filter(f => !f.startsWith('--'))
   if (!files.length) {

package/rules/doc-files/js/docs/docgen-crc.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-crc.mjs
 resource: npm/rules/doc-files/js/docgen-crc.mjs
 docgen:
-  crc: 6baf999b
+  crc: cca0a79f
 ---
 
 Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.

package/rules/doc-files/js/docs/docgen-extract-anchors.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-extract-anchors.mjs
 resource: npm/rules/doc-files/js/docgen-extract-anchors.mjs
 docgen:
-  crc: 49749e9c
+  crc: b675f159
   score: 80
 ---
 

package/rules/doc-files/js/docs/docgen-files-batch.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: 975d6cfa
+  crc: 18c96a58
   score: 95
 ---
 

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-judge-measure.mjs
 resource: npm/rules/doc-files/js/docgen-judge-measure.mjs
 docgen:
-  crc: 7f72e520
+  crc: e6e19732
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/rules/doc-files/js/docs/lint.md

@@ -3,7 +3,7 @@ type: JS Module
 title: lint.mjs
 resource: npm/rules/doc-files/js/lint.mjs
 docgen:
-  crc: fcdc1c2a
+  crc: ca055f8f
   score: 100
 ---
 

package/rules/doc-files/js/lint.mjs

@@ -1,19 +1,4 @@
-/**
- * Адаптер агрегатора `n-cursor lint` для правила doc-files (opportunistic LLM-fix
- * tier, спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md).
- *
- * Quick-фаза отримує список змінених файлів і мапить їх у пари в **обидва** боки:
- *  - змінене **джерело** (`.js/.mjs/.ts/.vue/.py/.rs`) → перевірка його доки `<dir>/docs/<stem>.md`;
- *  - змінена/видалена **дока** (`<dir>/docs/<stem>.md`) → перевірка відповідного джерела
- *    (той самий stem у каталозі над текою `docs`).
- * Ci-фаза (files === undefined) проганяє повний скан дерева.
- *
- * Детект — `missing` ∪ `crc-mismatch` (детермінований CRC, 0 LLM-токенів); degraded не блокує.
- * Поведінка за осями (правило має `meta.json: llmFix:true`):
- *  - `readOnly` (CI/hook): **лише детект** — нуль мутацій/LLM, exit 1 на stale (детермінований гейт);
- *  - fix-by-default + omlx **піднято**: opportunistic-генерація stale-доків → re-detect → 0 якщо полагоджено;
- *  - fix-by-default + omlx **недоступно**: fix пропущено (повідомлення) + exit 1 — гейт тримається, без false-green.
- */
+/** @see ./docs/lint.md */
 import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
 

package/rules/lint/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: 0f1d717c
+  crc: 0ab5b22c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---

package/rules/lint/js/orchestrate.mjs

@@ -1,18 +1,4 @@
-/**
- * Оркестратор `n-cursor lint` — дві ортогональні осі (spec 2026-06-14-lint-rule-consolidation
- * + компаньйон 2026-06-14-lint-orchestrator-fix-readonly-unification):
- *  - **scope** (`--full`): default = дельта vs origin (лише `per-file` правила);
- *    `--full` = весь репо (`per-file` ∪ `full` правила);
- *  - **behavior** (`--read-only`): default = fix; `--read-only` = лише детект без мутацій.
- *
- * Data-driven: сканує `rules/<id>/meta.json` за полем `lint` (`per-file`|`full`),
- * викликає `rules/<id>/js/lint.mjs` → `lint(files, cwd, { readOnly })`:
- *  - default scope: `files` = змінені відносно origin (`collectChangedFilesSince`);
- *  - `--full`:      `files = undefined` — весь проєкт.
- * Порядок правил — алфавітний. Fail-fast **лише в `--read-only`** (CI/детект): перший
- * ненульовий код спиняє. У fix-режимі (default) ненульовий код НЕ спиняє — проганяємо всі
- * правила й доходимо до кроку виправлення (конформність-драбина), повертаючи найгірший код.
- */
+/** @see ./docs/orchestrate.md */
 import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'

package/rules/text/lint/cspell-fix.mjs

@@ -14,6 +14,7 @@
  * Гейт: валідні слова після дописування у словник зникають; нерозкласифіковані та
  * typo лишаються → cspell повертає !=0 → exit 1 (людина доправляє одруки вручну).
  */
+import { env } from 'node:process'
 import { spawnSync } from 'node:child_process'
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
@@ -27,7 +28,7 @@ const UNKNOWN_WORD_RE = /Unknown word \(([^)]+)\)/u
 const MAX_CLASSIFY_WORDS = 80
 
 /** Локальна fix-модель (рішення: єдиний knob `N_LOCAL_MIN_MODEL`). */
-const fixModel = () => process.env.N_LOCAL_MIN_MODEL || ''
+const fixModel = () => env.N_LOCAL_MIN_MODEL || ''
 
 /**
  * Запускає `cspell .` із захопленням виводу.

package/rules/text/lint/docs/cspell-fix.md

@@ -3,24 +3,30 @@ type: JS Module
 title: cspell-fix.mjs
 resource: npm/rules/text/lint/cspell-fix.mjs
 docgen:
-  crc: b5585e0f
+  crc: 7b40e8f9
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 95
+  issues: anchor-miss:meta.json,judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Модуль інтегрує `cspell` у ланцюжок `lint-text` для виявлення орфографічних помилок. У режимі з можливістю виправлення, процес відбувається шляхом: детект (захоплення виводу) $\rightarrow$ групування знахідок по файлах $\rightarrow$ per-file `omlx-фікс` справжніх помилок (`llmLintFix`) $\rightarrow$ re-detect. У read-only режимі виконується лише детект, що гарантує нуль мутацій. Валідні терміни omlx залишаються, їх ловить повторний `cspell` (далі — у словник `@nitra/cspell-dict`).
+## Огляд
+
+Цей модуль інтегрує cspell у ланцюжок lint-text для класифікації невідомих слів згідно зі схемою omlx. Він витягує невідомі слова, класифікує їх за допомогою LLM (detect $\rightarrow$ omlx-класифікація) та автоматично дописує валідні терміни до словника `.cspell.json`. Нерозкласифіковані та ймовірні одруки залишаються для ручного рев'ю. Процес є read-only, оскільки він лише класифікує знахідки, а не переписує файли.
 
 ## Поведінка
 
-groupFindingsByFile групує вивід `cspell` за файлами, виділяючи знахідки.
-runCspellText запускає `cspell` для виявлення орфографічних помилок, а при вимкненому режимі читання виконує автоматичне виправлення помилок за допомогою зовнішнього інструменту для файлів, що містять справжні помилки, і повторно перевіряє файли.
+unknownWords витягує унікальні невідомі слова з виводу cspell.
+appendWordsToDict дописує класифіковані валідні слова до файлу .cspell.json, оновлюючи словник.
+runCspellText запускає cspell, класифікує знахідки за допомогою LLM (якщо увімкнено) та повторно перевіряє код, повертаючи 0 при чистоті або 1 при знахідках.
 
 ## Публічний API
 
-groupFindingsByFile — збирає знайдені помилки cspell у групи за файлами.
-runCspellText — виконує перевірку тексту за правилами cspell, застосовуючи автоматичне виправлення від omlx.
+unknownWords — Збирає унікальні слова, які не були знайдені у словнику cspell.
+appendWordsToDict — Додає зібрані слова до файлу `.cspell.json#words` у відсортованому та унікальному вигляді для перегляду у Git.
+runCspellText — Виконує перевірку тексту за допомогою cspell, класифікуючи слова та оновлюючи словник за новою схемою.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/lib/adr/docs/normalize-cli.md

@@ -3,26 +3,27 @@ type: JS Module
 title: normalize-cli.mjs
 resource: npm/scripts/lib/adr/normalize-cli.mjs
 docgen:
-  crc: ce2f13af
+  crc: 63a18347
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Цей файл є CLI-обгорткою для локального ADR-нормалізатора (`n-cursor adr-normalize-local`). Він використовується скриптом `.claude/hooks/normalize-decisions.sh` як локальний бекенд для обробки батчу чернеток та списку чистих ADR. Обгортка зчитує шляхи до чернеток та параметри з аргументів командного рядка та змінних середовища, а потім проганяє `normalizePipeline`. Результатом роботи є вивід JSON-контракту з операціями у stdout, який парситься зовнішнім скриптом. Прогрес відображається у stderr.
+## Огляд
+
+Цей файл є CLI-обгорткою для локального нормалізатора ADR. Він зчитує шляхи до чернеток (`--batch <file>`) та список чистих ADR (`--clean <file>`), використовуючи директорію ADR (`--adr-dir <dir>`) для резолву шляхів. Обгортка запускає `normalizePipeline`, яка генерує JSON-контракт у форматі `{ "operations": [...] }` та виводить його у stdout для подальшого парсингу bash-скриптом. Прогрес та помилки записуються у stderr. Поведінка нормалізатора може бути змінена через змінні середовища: `ADR_NORMALIZE_ALLOW_CLOUD` контролює можливість хмарної ескалації, а `ADR_NORMALIZE_VOTES` визначає кількість голосів self-consistency для чистих ADR.
 
 ## Поведінка
 
-1. `runAdrNormalizeLocalCli` парсить вхідні аргументи для визначення шляху до чернеток батчу, списку чистих ADR та каталогу ADR.
-2. Якщо не надано файл батчу, `runAdrNormalizeLocalCli` виводить повідомлення про використання та завершує роботу з кодом помилки.
-3. `runAdrNormalizeLocalCli` зчитує шляхи до чернеток батчу з вказаного файлу.
-4. Для кожної чернетки `runAdrNormalizeLocalCli` зчитує вміст файлу, резолвячи шлях відносно каталогу ADR, і створює об'єкт чернетки.
-5. `runAdrNormalizeLocalCli` зчитує список назв чистих ADR з файлу, якщо він наданий.
-6. `runAdrNormalizeLocalCli` зчитує значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES` для визначення параметрів нормалізації.
-7. `runAdrNormalizeLocalCli` викликає логіку нормалізації, передаючи чернетки, список чистих ADR та параметри, при цьому прогрес виводиться у stderr.
-8. `runAdrNormalizeLocalCli` виводить кількість операцій та статистику нормалізації у stderr.
-9. `runAdrNormalizeLocalCli` виводить деталі рішень нормалізації у stderr.
-10. `runAdrNormalizeLocalCli` друкує JSON-об'єкт, що містить операції, у stdout.
-11. `runAdrNormalizeLocalCli` завершує роботу з кодом успіху.
+1. Викликати runAdrNormalizeLocalCli.
+2. Зчитувати список шляхів до чернеток батчу з файлу, вказаного через аргумент `--batch`.
+3. Зчитувати список імен чистих ADR (кандидатів до злиття) з файлу, вказаного через аргумент `--clean`, якщо він наданий.
+4. Визначати директорію ADR, використовуючи аргумент `--adr-dir` або за замовчуванням `cwd/docs/adr`.
+5. Зчитувати вміст кожної чернетки батчу, резолвя шляхи відносно `--adr-dir`.
+6. Зчитувати значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES`.
+7. Викликати внутрішній механізм нормалізації, передаючи зібрані чернетки, список чистих ADR, та конфігурацію, отриману з змінних середовища.
+8. Виводити інформацію про прогрес та статистику в stderr.
+9. Виводити JSON-об'єкт, що містить операції, у stdout.
 
 ## Публічний API
 
@@ -30,5 +31,4 @@ runAdrNormalizeLocalCli — запускає субкоманду, виводя
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/adr/normalize-cli.mjs

@@ -16,6 +16,7 @@
  *   ADR_NORMALIZE_ALLOW_CLOUD=1  дозволити хмарну ескалацію tier-каскаду (default off)
  *   ADR_NORMALIZE_VOTES=N        голосів self-consistency для clean-ребер (default 2)
  */
+import { env } from 'node:process'
 import { readFileSync } from 'node:fs'
 import { basename, isAbsolute, join } from 'node:path'
 import { normalizePipeline } from './normalize-pipeline.mjs'
@@ -57,8 +58,8 @@ export function runAdrNormalizeLocalCli(argv) {
   })
   const cleanList = args.clean ? readLines(args.clean).map((c) => basename(c)) : []
 
-  const allowCloud = process.env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
-  const votes = Number(process.env.ADR_NORMALIZE_VOTES) || 2
+  const allowCloud = env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
+  const votes = Number(env.ADR_NORMALIZE_VOTES) || 2
 
   const { operations, stats, trace } = normalizePipeline(drafts, cleanList, {
     allowCloud,

package/scripts/lib/fix/docs/llm-worker.md

@@ -3,7 +3,7 @@ type: JS Module
 title: llm-worker.mjs
 resource: npm/scripts/lib/fix/llm-worker.mjs
 docgen:
-  crc: de9eb68c
+  crc: 857c510e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -18,7 +18,7 @@ docgen:
 
 ## Публічний API
 
-- `runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення; `opts`: `model`, `feedback`, `caller`. Повертає `{ ok, error, changes, diagnosis }`.
+- `runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення; `opts`: `model`, `feedback`, `caller`, `timeoutMs` (per-tier ліміт виклику; драбина задає коротший для локальних рунгів). Повертає `{ ok, error, changes, diagnosis }`.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/docs/orchestrator.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: 78dfe86b
+  crc: d327ab6d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -19,7 +19,8 @@ docgen:
    - рунг `local-min` — перший прохід без feedback;
    - рунг `local-min-retry` — той самий локальний тир, але з feedback попереднього рунга (попередні зміни + залишковий violation);
    - рунги `cloud-min` / `cloud-avg` — хмарні моделі (через pi), теж із feedback.
-5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
+   Кожен рунг має per-tier `timeoutMs`: локальні **fail-fast** (`N_LOCAL_FIX_TIMEOUT_MS`, дефолт 45s — не палити стіну 120s на повільному локальному inference), хмарні — повний (`N_CLOUD_FIX_TIMEOUT_MS`, дефолт 120s).
+5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; хмарний транспортний збій (pi таймаут/spawn) обриває драбину, щоб не палити avg-бюджет на ту саму стіну; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
 6. Після обробки всіх правил — фінальна перевірка. Усі чисті → успіх; інакше — ознака нерозв'язаних.
 
 ## Публічний API

package/scripts/lib/fix/llm-worker.mjs

@@ -117,11 +117,12 @@ function buildPrompt(ruleId, ruleMdc, output, files, feedback = null) {
  * @param {string} prompt текст промпта
  * @param {string} model назва моделі (provider/id, `omlx/...` або '')
  * @param {string} caller мітка викликача для wire-trace (`fix:<rule>:<rung>`)
+ * @param {number} [timeoutMs] ліміт виклику (драбина задає per-tier; undefined → дефолт callLlm)
  * @returns {{ text: string, error?: string }} текст відповіді або повідомлення про помилку
  */
-function callModel(prompt, model, caller) {
+function callModel(prompt, model, caller, timeoutMs) {
   try {
-    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller }) }
+    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs, caller }) }
   } catch (error) {
     const msg = String(error.message)
     if (API_KEY_RE.test(msg)) {
@@ -146,9 +147,10 @@ function callModel(prompt, model, caller) {
  * @param {string} ruleId ID правила
  * @param {string} violationOutput  output з fix check для цього rule
  * @param {string} projectRoot      абсолютний шлях до кореня проєкту
- * @param {{ model?: string, feedback?: object|null, caller?: string }} opts опції:
+ * @param {{ model?: string, feedback?: object|null, caller?: string, timeoutMs?: number }} opts опції:
  *   `model` — перевизначення моделі; `feedback` — контекст попереднього рунга
- *   драбини (retry-with-feedback); `caller` — мітка для wire-trace
+ *   драбини (retry-with-feedback); `caller` — мітка для wire-trace; `timeoutMs` —
+ *   per-tier ліміт виклику (драбина: локалі fail-fast, хмара повний)
  * @returns {{ ok: boolean, error?: string, changes: Array<{path:string}>, diagnosis: string|null }}
  *   статус виправлення, помилка, запропоновані зміни і само-аналіз моделі
  */
@@ -156,6 +158,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const model = opts.model ?? MODEL
   const feedback = opts.feedback ?? null
   const caller = opts.caller ?? 'fix'
+  const timeoutMs = opts.timeoutMs
 
   // 1. Читаємо rule .mdc
   const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
@@ -166,7 +169,7 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
 
   // 3. Будуємо prompt і викликаємо модель
   const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files, feedback)
-  const { text, error: modelError } = callModel(prompt, model, caller)
+  const { text, error: modelError } = callModel(prompt, model, caller, timeoutMs)
 
   if (modelError) return { ok: false, error: modelError, changes: [], diagnosis: null }
   if (!text) return { ok: false, error: 'model returned empty response', changes: [], diagnosis: null }

package/scripts/lib/fix/orchestrator.mjs

@@ -1,5 +1,6 @@
 /** @see ./docs/orchestrator.md */
 
+import { env } from 'node:process'
 import { runFixCheck } from './run-fix-check.mjs'
 import { runT0AutoCli } from './t0.mjs'
 import { logEscalation } from './escalation-log.mjs'
@@ -13,9 +14,24 @@ import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
  */
 const DEFAULT_MAX_AVG = 3
 
+/**
+ * Timeout одного LLM-виклику за тиром. Локальні рунги **fail-fast**: не палити
+ * стіну 120s на повільному 4b (curl exit 28) — швидше абортнути й ескалувати.
+ * Хмарні — повний. Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
+ */
+const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
+const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+
 /** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */
 const NO_KEY_RE = /немає ключа|api key/i
 
+/**
+ * Хмарний транспорт (pi) упав на рівні процесу: таймаут/spawn-помилка. Стіна часу
+ * однакова для всіх cloud-рунгів (та сама pi-транспортна стіна), а cloud-avg — інша
+ * модель, не більший timeout. Ескалація на неї лише спалить avg-бюджет → обрив.
+ */
+const CLOUD_TRANSPORT_RE = /etimedout|timed out|pi error/i
+
 /**
  * Будує драбину ескалації за наявними тирами (спека 2026-06-19-fix-escalation-cascade):
  *  1. `local-min`       — `N_LOCAL_MIN_MODEL`, перший прохід;
@@ -24,14 +40,14 @@ const NO_KEY_RE = /немає ключа|api key/i
  *  4. `cloud-avg`       — `N_CLOUD_AVG_MODEL` (через pi), з feedback, під avg-кепом.
  * Рунги з незаданим тиром (`''`) відсіюються — драбина стискається до доступних.
  * @param {{ localMin: string, cloudMin: string, cloudAvg: string }} models тири з env
- * @returns {Array<{ tier: string, model: string, feedback: boolean, local: boolean, isAvg: boolean }>} драбина
+ * @returns {Array<{ tier: string, model: string, feedback: boolean, local: boolean, isAvg: boolean, timeoutMs: number }>} драбина
  */
 export function buildLadder({ localMin, cloudMin, cloudAvg }) {
   return [
-    { tier: 'local-min', model: localMin, feedback: false, local: true, isAvg: false },
-    { tier: 'local-min-retry', model: localMin, feedback: true, local: true, isAvg: false },
-    { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false },
-    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true }
+    { tier: 'local-min', model: localMin, feedback: false, local: true, isAvg: false, timeoutMs: LOCAL_TIMEOUT_MS },
+    { tier: 'local-min-retry', model: localMin, feedback: true, local: true, isAvg: false, timeoutMs: LOCAL_TIMEOUT_MS },
+    { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false, timeoutMs: CLOUD_TIMEOUT_MS },
+    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_TIMEOUT_MS }
   ].filter(r => r.model)
 }
 
@@ -40,6 +56,8 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
  *  - `break`     — відсутній API-ключ на хмарному (інші хмарні рунги теж без ключа);
  *  - `skip-model` — systemic-помилка локального тиру (memory-guard/auth/down): повтор
  *                   тієї ж моделі марний → пропустити рунги з цим model.
+ *  - `break`     — також хмарний транспорт упав (pi таймаут/spawn): решта cloud-рунгів
+ *                  під тією ж стіною → обрив, щоб не палити avg-бюджет.
  * @param {{ local: boolean }} rung поточний рунг
  * @param {string|null|undefined} error помилка виклику worker
  * @returns {'break'|'skip-model'|null} дія для драбини
@@ -48,6 +66,7 @@ function decideAfterFailure(rung, error) {
   if (!error) return null
   if (NO_KEY_RE.test(error)) return 'break'
   if (rung.local && classifyOmlxError(error) === 'systemic') return 'skip-model'
+  if (!rung.local && CLOUD_TRANSPORT_RE.test(error)) return 'break'
   return null
 }
 
@@ -93,7 +112,8 @@ export async function escalateRule(rule, cwd, deps) {
     const res = worker.runLlmWorker(rule.ruleId, currentViolation, cwd, {
       model: rung.model,
       feedback: rung.feedback ? feedback : null,
-      caller: `fix:${rule.ruleId}:${rung.tier}`
+      caller: `fix:${rule.ruleId}:${rung.tier}`,
+      timeoutMs: rung.timeoutMs
     })
     if (rung.isAvg) avgUsed++
 

package/skills/doc-aggregate/js/docgen-ignore.mjs

@@ -1,9 +1,2 @@
-/**
- * Re-export спільного списку ignore-глобів із правила doc-files.
- *
- * Канонічне джерело — `npm/rules/doc-files/js/docgen-ignore.mjs`: скіл doc-aggregate
- * і правило doc-files мусять бачити однакове дерево кодових файлів, інакше агрегат
- * посилатиметься на файли без док (або навпаки). Залежність спрямована
- * doc-aggregate → doc-files за ADR про розбиття docgen.
- */
+/** @see ./docs/docgen-ignore.md */
 export * from '../../../rules/doc-files/js/docgen-ignore.mjs'

package/skills/doc-aggregate/js/docs/docgen-ignore.md

@@ -3,7 +3,7 @@ type: JS Module
 title: docgen-ignore.mjs
 resource: npm/skills/doc-aggregate/js/docgen-ignore.mjs
 docgen:
-  crc: 5faaffd0
+  crc: 3b579230
 ---
 
 Re-export спільного списку ignore-глобів зі скіла doc-files: обидва скіли документації (пофайлові доки й агрегати) мусять бачити однакове дерево кодових файлів, інакше агрегат посилатиметься на файли без док або навпаки.