@nitra/cursor 12.10.0 → 12.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.11.0] - 2026-06-25
+
+### Changed
+
+- Додано перевірку на наявність `CHANGELOG.md` та його формату в workspace-ах
+
 ## [12.10.0] - 2026-06-24
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.10.0",
+  "version": "12.11.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/adr/js/docs/hooks.md

@@ -3,40 +3,30 @@ type: JS Module
 title: hooks.mjs
 resource: npm/rules/adr/js/hooks.mjs
 docgen:
-  crc: 3f239faf
+  crc: 7195231e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Файл надає публічну функцію `check` для валідації даних. Код використовує конфігурацію з файлу `.local.json` для визначення логіки. Функція працює у режимі, де невдачі повертають `false` або `null` замість генерації винятків. Повідомлення про події передаються за допомогою маркера (adr.mdc).
+## Огляд
 
-## Поведінка
-
-1. Перевірка канонічності скриптів
-   Проводиться перевірка наявності та відповідності логіки між скриптами, визначеними в артефактах, і їхніми канонічними версіями. У разі невідповідності повертається сигнал про необхідність повторного синхронізації.
-
-2. Валідація налаштувань проєкту
-   Перевіряється наявність файлу `.claude/settings.json` для підтвердження коректності конфігурації відповідно до вимог (adr.mdc).
-
-3. Перевірка конфігурації хуків Cursor
-   Перевіряється, чи містить конфігурацію Cursor необхідні стоп-хуки для кожного визначеного скрипта.
+Модуль перевіряє стан проєкту, валідуючи конфігураційні файли (`settings.json`, `hooks.json`, `settings.local.json`) та перевіряючи наявність структур для документації (adr.mdc). Перевірка включає перевірку наявності необхідних елементів, при цьому шляхи `.git` свідомо ігноруються.
 
-4. Перевірка ігнорування логів
-   Перевіряється вміст файлу `.gitignore` на відповідність ігнорування кожного лог-файлу хука.
-
-5. Перевірка покриття логів
-   Перевіряється, чи покриває конфігурація `.gitignore` всі необхідні лог-файли.
-
-6. Перевірка доступності CLI
-   Перевіряється наявність бінарних файлів `claude` або `cursor-agent` у системному PATH. Якщо жодного не знайдено, це інформується як попередження, оскільки хук працюватиме у режимі мовчки.
-
-## Публічний API
+## Поведінка
 
-check — перевіряє, чи відповідає проєкт вимогам adr.mdc (adr.mdc).
+1. Викликається `check` для запуску повного набору перевірок проєкту.
+2. Перевіряється наявність та збіг конфігураційних скриптів хуків у проєкті з канонічними версіями.
+3. Перевіряється наявність конфігурацій проєкту, зокрема `settings.json`.
+4. Перевіряється, чи містить конфігурація хуків проєкту (`hooks.json`) необхідні маркери для зупинення (stop-hook) кожного артефакту хука.
+5. Перевіряється, чи ігнорує файл `.gitignore` лог-файли кожного хука.
+6. Перевіряється, чи ігнорує файл `.gitignore` файли стану та блокування, пов'язані з нормалізацією хуків.
+7. Перевіряється наявність каталогу `docs/adr/` для зберігання ADR-ів.
+8. Перевіряється доступність LLM CLI (`claude` або `cursor-agent`) у системному шляху.
+9. Повертається код виходу, що відображає результати всіх перевірок.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдалої перевірки повертає `false`/`null` замість винятку.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
 - Свідомо пропускає шляхи: `.git`.
-- Не звертається до мережі.

package/rules/adr/js/hooks.mjs

@@ -55,6 +55,9 @@ function gitignoreLineCoversHookLog(line, logPath) {
   if (line === '.claude/hooks/*.log' || line === '.claude/hooks/**/*.log') {
     return true
   }
+  if (line === '.claude/hooks/*' || line === '.claude/hooks/**') {
+    return true
+  }
   if (line === '*.log' || line === '**/*.log') {
     return true
   }
@@ -264,6 +267,60 @@ function checkLlmCliAvailable(reporter) {
  * @param {string} [cwd] корінь репозиторію
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
  */
+/** Файли стану/блокування normalize-хука, які не мають потрапляти в git. */
+const NORMALIZE_STATE_FILES = ['.normalize-state', '.normalize.lock']
+const CLAUDE_HOOKS_REL = '.claude/hooks'
+
+/**
+ * Перевіряє рядок `.gitignore` на покриття конкретного state/lock файлу.
+ * @param {string} line нормалізований (trim) рядок
+ * @param {string} statePath відносний шлях файлу (наприклад `.claude/hooks/.normalize-state`)
+ * @returns {boolean} true — рядок покриває файл
+ */
+function gitignoreLineCoversStatePath(line, statePath) {
+  if (line === statePath) return true
+  // .claude/hooks/* або .claude/hooks/**
+  if (line === `${CLAUDE_HOOKS_REL}/*` || line === `${CLAUDE_HOOKS_REL}/**`) return true
+  return false
+}
+
+/**
+ * Перевіряє `.gitignore` на наявність рядків для файлів стану normalize-хука.
+ * @param {import('../../../scripts/lib/check-reporter.mjs').CheckReporter} reporter
+ * @param {string} cwd корінь репозиторію
+ * @returns {Promise<void>}
+ */
+async function checkGitignoreForStateFiles(reporter, cwd) {
+  const { pass, fail } = reporter
+  const gitignoreAbs = join(cwd, '.gitignore')
+  const content = existsSync(gitignoreAbs) ? await readFile(gitignoreAbs, 'utf8') : ''
+  const lines = content.split(EOL_RE).map(l => l.trim())
+  for (const file of NORMALIZE_STATE_FILES) {
+    const statePath = `${CLAUDE_HOOKS_REL}/${file}`
+    if (lines.some(l => gitignoreLineCoversStatePath(l, statePath))) {
+      pass(`.gitignore покриває ${statePath}`)
+    } else {
+      fail(`.gitignore не ігнорує \`${statePath}\` — додай рядок (adr.mdc)`)
+    }
+  }
+}
+
+/**
+ * Перевіряє наявність каталогу `docs/adr/` — обов'язкового місця зберігання ADR-ів.
+ * @param {import('../../../scripts/lib/check-reporter.mjs').CheckReporter} reporter
+ * @param {string} cwd корінь репозиторію
+ * @returns {void}
+ */
+function checkDocsAdrDir(reporter, cwd) {
+  const { pass, fail } = reporter
+  const adrDir = join(cwd, 'docs', 'adr')
+  if (existsSync(adrDir)) {
+    pass('docs/adr/ існує (каталог ADR-ів)')
+  } else {
+    fail('docs/adr/ відсутній — створи каталог для ADR-ів (adr.mdc)')
+  }
+}
+
 export async function check(cwd = process.cwd()) {
   const reporter = createCheckReporter()
   for (const { scriptName } of HOOK_ARTIFACTS) {
@@ -272,6 +329,8 @@ export async function check(cwd = process.cwd()) {
   checkProjectSettings(reporter, cwd)
   await checkCursorHooks(reporter, cwd)
   await checkGitignore(reporter, cwd)
+  await checkGitignoreForStateFiles(reporter, cwd)
+  checkDocsAdrDir(reporter, cwd)
   checkLlmCliAvailable(reporter)
   return reporter.getExitCode()
 }

package/rules/changelog/js/consistency.mjs

@@ -1,5 +1,7 @@
 /** @see ./docs/consistency.md */
 import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import { promisify } from 'node:util'
 
@@ -379,6 +381,46 @@ function createDefaultGetPublishedVersion() {
  * @param {(msg: string) => void} pass параметр
  * @param {(msg: string) => void} fail параметр
  */
+/**
+ * Перевіряє наявність `CHANGELOG.md` у воркспейсі.
+ * @param {string} ws відносний шлях воркспейсу від кореня репо
+ * @param {string} label мітка для повідомлень
+ * @param {string} cwd корінь репозиторію
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ * @returns {boolean} true — файл існує
+ */
+function checkChangelogFileExists(ws, label, cwd, pass, fail) {
+  const path = join(cwd, ws, 'CHANGELOG.md')
+  if (existsSync(path)) {
+    pass(`${label}: CHANGELOG.md існує`)
+    return true
+  }
+  fail(`${label}: CHANGELOG.md відсутній — створи файл за форматом Keep a Changelog (n-changelog.mdc)`)
+  return false
+}
+
+/**
+ * Перевіряє базовий формат `CHANGELOG.md`: наявність H1 `# Changelog`.
+ * Версійні секції `## [x.y.z]` не вимагаються для нових workspace-ів без релізів.
+ * @param {string} ws відносний шлях воркспейсу від кореня репо
+ * @param {string} label мітка для повідомлень
+ * @param {string} cwd корінь репозиторію
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ * @returns {Promise<void>}
+ */
+async function checkChangelogFormat(ws, label, cwd, pass, fail) {
+  const path = join(cwd, ws, 'CHANGELOG.md')
+  const content = await readFile(path, 'utf8')
+  const hasH1 = content.split('\n').some(l => l.trimEnd() === '# Changelog')
+  if (hasH1) {
+    pass(`${label}: CHANGELOG.md має рядок "# Changelog"`)
+  } else {
+    fail(`${label}: CHANGELOG.md не має рядка "# Changelog" — перший рядок має бути H1-заголовком (n-changelog.mdc)`)
+  }
+}
+
 function checkNpmFilesArrayContainsChangelog(manifest, pass, fail) {
   if (manifest.kind !== 'npm' || !manifest.npmFiles) return
   const pkgPath = manifestFilePath(manifest.ws, manifest)
@@ -542,6 +584,10 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, _Vcurrent, sub
 async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVersion, autofix, pass, fail, cwd) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
+  const changelogExists = checkChangelogFileExists(manifest.ws, label, cwd, pass, fail)
+  if (changelogExists) {
+    await checkChangelogFormat(manifest.ws, label, cwd, pass, fail)
+  }
   const Vcurrent = manifest.version
   if (!Vcurrent) {
     fail(`${label}: у ${mf} відсутнє поле version (registry-published воркспейс)`)
@@ -635,6 +681,14 @@ async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel
 async function runLocalOnlyChecks(localOnly, subWorkspaces, autofix, pass, fail, cwd) {
   if (localOnly.length === 0) return
 
+  for (const manifest of localOnly) {
+    const label = workspaceLabel(manifest)
+    const exists = checkChangelogFileExists(manifest.ws, label, cwd, pass, fail)
+    if (exists) {
+      await checkChangelogFormat(manifest.ws, label, cwd, pass, fail)
+    }
+  }
+
   if (!(await isInsideGitRepo(cwd))) {
     pass('changelog: не git-репозиторій — local-only перевірку пропущено')
     return

package/rules/changelog/js/docs/consistency.md

@@ -3,28 +3,35 @@ type: JS Module
 title: consistency.mjs
 resource: npm/rules/changelog/js/consistency.mjs
 docgen:
-  crc: 92b7c3f0
+  crc: a9bebf31
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 95
 ---
 
 ## Огляд
 
-Компонент виконує перевірку стану проєктів у монорепозиторії. Він звертається до мережі для порівняння версій з реєстром, зокрема https://pypi.org/pypi/, та аналізує зміни, посилаючись на (n-changelog.mdc). Код спирається на конфігурацію, визначену у res.json. При виявленні невідповідностей компонент перехоплює помилки (fail-safe) і повертає порожнє значення замість кидання винятків.
+Модуль сканує монорепозиторій, ідентифікує проєкти та порівнює їхні версії з даними, отриманими з https://pypi.org/pypi/, для верифікації відповідності версій. Для проєктів, що не призначені для публікації, виконуються локальні перевірки на відповідність файлу `CHANGELOG.md` конфігурації, визначеній у res.json.
 
 ## Поведінка
 
-1. `check` ініціалізує репортер та визначає режим автоматичного виправлення на основі змінної середовища.
-2. `check` зчитує список усіх кореневих каталогів проєктів у монорепозиторії.
-3. `check` класифікує знайдені проєкти на ті, що можуть бути опубліковані в реєстрі, та ті, що є локальними.
-4. Для кожного проєкту, що може бути опублікований, `check` викликає перевірку опублікованого воркспейсу.
-5. Перевірка опублікованого воркспейсу порівнює версію у маніфесті з опублікованою версією, отриманою через мережевий запит до реєстру (наприклад, https://pypi.org/pypi/).
-6. Якщо версія у маніфесті випереджає опубліковану, `check` повідомляє про заборонений ручний bump поза CI.
-7. Якщо версія у маніфесті відповідає опублікованій, `check` перевіряє, чи є релевантні зміни у файловій системі відносно базової точки порівняння (наприклад, `origin/main`).
-8. Якщо зміни існують, але відсутній change-файл, `check` або автоматично створює його (у режимі autofix), або повідомляє про необхідність ручного створення, посилаючись на (n-changelog.mdc).
-9. Для кожного локального проєкту `check` порівнює стан з базовою точкою порівняння.
-10. Якщо зміни існують, але відсутній change-файл, `check` або автоматично створює його (у режимі autofix), або повідомляє про необхідність ручного створення, посилаючись на (n-changelog.mdc).
-11. `check` повертає кінцевий код виходу на основі накопичених повідомлень про помилки.
+1. `check` ініціалізує репортер для збору результатів перевірки.
+2. `check` визначає робочий каталог та режим автоматичного виправлення на основі змінних середовища.
+3. `check` знаходить усі кореневі каталоги проєктів у монорепозиторії.
+4. `check` класифікує знайдені проєкти на ті, що можуть бути опубліковані в реєстрі, та ті, що є локальними.
+5. Для кожного проєкту, що може бути опублікованим, `check` перевіряє його відповідність вимогам:
+    а. Перевіряє наявність файлу `CHANGELOG.md`.
+    б. Перевіряє базовий формат `CHANGELOG.md` на наявність заголовка `# Changelog`.
+    в. Якщо проєкт має поле `version` у маніфесті, `check` порівнює його з опублікованою версією, отриманою через мережевий запит до https://pypi.org/pypi/ або `npm view`.
+    г. Якщо версія у проєкті випереджає опубліковану, `check` повідомляє про заборонений ручний bump.
+    д. Якщо версія у проєкті відстає від опублікованої, `check` повідомляє про відставання локальної копії від реєстру.
+    е. Якщо версії збігаються, `check` перевіряє, чи є незрелі зміни у проєкті відносно базового релізу.
+    ж. Якщо проєкт має незрелі зміни, `check` перевіряє наявність change-файлу. Якщо його немає, `check` або повідомляє про необхідність створити його (якщо не в режимі autofix), або автоматично створює його та додає до індексу.
+6. `check` виконує локальні перевірки для проєктів, які не призначені для публікації:
+    а. Для кожного локального проєкту `check` перевіряє наявність файлу `CHANGELOG.md` та його формат.
+    б. `check` визначає точку порівняння (базу) на основі поточної гілки.
+    в. `check` перевіряє, чи є релевантні зміни у проєкті відносно цієї бази.
+    г. Якщо зміни є, `check` перевіряє наявність change-файлу. Якщо його немає, `check` або повідомляє про необхідність створити його (якщо не в режимі autofix), або автоматично створює його та додає до індексу.
+7. `check` повертає кінцевий код завершення, що відображає результати всіх перевірок.
 
 ## Гарантії поведінки
 

package/rules/changelog/js/docs/index.md

@@ -6,6 +6,6 @@ resource: npm/rules/changelog/js/
 
 # npm/rules/changelog/js
 
-| Файл                              | Тип       |
-| --------------------------------- | --------- |
+| Файл | Тип |
+|---|---|
 | [consistency.mjs](consistency.md) | JS Module |

package/rules/python/policy/lint_python_yml/lint_python_yml.rego

@@ -43,6 +43,15 @@ deny contains msg if {
 	msg := sprintf("lint-python.yml: відсутній step з `uses: %s` (python.mdc)", [required_use])
 }
 
+deny contains msg if {
+	some job in object.get(input, "jobs", {})
+	some step in object.get(job, "steps", [])
+	object.get(step, "uses", "") == "actions/checkout@v6"
+	creds := object.get(object.get(step, "with", {}), "persist-credentials", true)
+	creds != false
+	msg := "lint-python.yml: actions/checkout@v6 потребує `with: persist-credentials: false` (python.mdc)"
+}
+
 deny contains msg if {
 	some job in data.template.snippet.jobs
 	some step in job.steps

package/rules/python/policy/pyproject_toml/pyproject_toml.rego

@@ -21,7 +21,7 @@ deny contains msg if {
 	msg := sprintf("pyproject.toml: [tool.%s] — %s", [key, reason])
 }
 
-# ── PEP 621: обовʼязкові [project].name / [project].version ──────────────────
+# ── PEP 621: обовʼязкові [project].* ─────────────────────────────────────────
 
 deny contains msg if {
 	not project_field_set("name")
@@ -33,7 +33,21 @@ deny contains msg if {
 	msg := "pyproject.toml: відсутній статичний [project].version (PEP 621, python.mdc)"
 }
 
+deny contains msg if {
+	not project_field_set("requires-python")
+	msg := "pyproject.toml: відсутній [project].requires-python (наприклад '>=3.12') (PEP 621, python.mdc)"
+}
+
+deny contains msg if {
+	not project_key_exists("dependencies")
+	msg := "pyproject.toml: відсутній [project].dependencies (навіть порожній список `[]`) (PEP 621, python.mdc)"
+}
+
 project_field_set(key) if {
 	value := object.get(object.get(input, "project", {}), key, "")
 	value != ""
 }
+
+project_key_exists(key) if {
+	key in object.keys(object.get(input, "project", {}))
+}

package/rules/vue/js/docs/packages.md

@@ -3,33 +3,28 @@ type: JS Module
 title: packages.mjs
 resource: npm/rules/vue/js/packages.mjs
 docgen:
-  crc: 6119ae9c
-  score: 85
+  crc: 8589151d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-isVueComponentLibraryPkg
-Перевіряє, чи є пакет бібліотекою компонентів Vue шляхом перевірки `peerDependencies`.
+## Огляд
 
-check
-Перевіряє залежності та конфігурацію vite.config одного Vue-пакета.
+Модуль визначає, чи є пакет бібліотекою компонентів Vue, виходячи з даних у `package.json`, `jsconfig.json`, `package-lock.json`, `extensions.json`. Він також перевіряє відповідність усіх пакетів, що залежать від `vue`, критеріям, описаним у `vue.mdc`, і повертає код виходу.
 
 ## Поведінка
 
-isVueComponentLibraryPkg
-Визначає, чи є пакет бібліотекою компонентів Vue через peerDependencies
-
-check
-Перевіряє залежності та vite.config одного Vue-пакета
+isVueComponentLibraryPkg визначає, чи є пакет бібліотекою компонентів Vue, перевіряючи наявність `vue` у `peerDependencies` його `package.json`.
+check перевіряє відповідність проєкту правилам vue.mdc для всіх пакетів, що містять `vue` у `dependencies`, і повертає код виходу. При цьому ігноруються шляхи `.git` та `node_modules`.
 
 ## Публічний API
 
-isVueComponentLibraryPkg — забезпечує, що `+` використовується для підхоплення `vite-env.d.ts` та `.vue`.
-passFn — перевіряє наявність `prefixjsconfig.json`.
-check — перевіряє, чи є `vue` у `peerDependencies` пакету бібліотеки. Якщо `vue` є залежністю, то правило авто-імпорту (заборона value-імпортів з `'vue'`) не застосовується до цієї бібліотеки, оскільки імпорти з `'vue'` повинні бути явними.
+isVueComponentLibraryPkg — визначає, чи є пакет бібліотекою компонентів Vue, щоб IDE коректно обробляла файли `.vue` та `vite-env.d.ts`.
+passFn — підтверджує наявність файлу `jsconfig.json` у вказаній директорії.
+check — перевіряє, чи відповідає проєкт вимогам vue.mdc, а саме: чи є `vue` у залежностях кореневого та всіх workspace-пакетів.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
 - Свідомо пропускає шляхи: `.git`, `node_modules`.
-- Не звертається до мережі.

package/rules/vue/js/packages.mjs

@@ -1,5 +1,5 @@
 /** @see ./docs/packages.md */
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'
 
@@ -500,6 +500,45 @@ async function checkVueVolarRecommendation(pass, fail, cwd) {
   }
 }
 
+// Vitest-пакети мусять бути у кореневому devDependencies монорепо,
+// бо npm-module правило забороняє devDeps у published Vue workspace.
+const ROOT_VITEST_DEV_DEPS = ['vitest', '@vitest/coverage-v8', '@stryker-mutator/vitest-runner']
+
+/**
+ * Перевіряє, що кореневий `package.json` монорепо містить vitest-залежності
+ * у `devDependencies`. Викликається тільки коли є Vue-пакети у воркспейсі.
+ * @param {string} cwd корінь репозиторію
+ * @param {(msg: string) => void} pass pass callback
+ * @param {(msg: string) => void} fail fail callback
+ * @returns {void}
+ */
+function checkRootVitestDevDeps(cwd, pass, fail) {
+  const rootPkgPath = join(cwd, 'package.json')
+  if (!existsSync(rootPkgPath)) {
+    fail('vue: кореневий package.json не знайдено — неможливо перевірити vitest devDependencies')
+    return
+  }
+  let rootPkg
+  try {
+    rootPkg = JSON.parse(readFileSync(rootPkgPath, 'utf8'))
+  } catch {
+    fail('vue: кореневий package.json не вдалося розпарсити — неможливо перевірити vitest devDependencies')
+    return
+  }
+  const devDeps =
+    rootPkg.devDependencies && typeof rootPkg.devDependencies === 'object' ? Object.keys(rootPkg.devDependencies) : []
+  const missing = ROOT_VITEST_DEV_DEPS.filter(p => !devDeps.includes(p))
+  if (missing.length === 0) {
+    pass(`vue: кореневий devDependencies містить ${ROOT_VITEST_DEV_DEPS.join(', ')} (vue.mdc testing)`)
+  } else {
+    for (const pkg of missing) {
+      fail(
+        `vue: кореневий devDependencies не містить '${pkg}' — перенеси з Vue workspace у корінь монорепо (vue.mdc testing)`
+      )
+    }
+  }
+}
+
 /**
  * Перевіряє відповідність проєкту правилам vue.mdc (корінь і всі workspace-пакети з `vue` у dependencies).
  * @param {string} [cwd] корінь репозиторію
@@ -519,6 +558,7 @@ export async function check(cwd = process.cwd()) {
   }
 
   await checkVueVolarRecommendation(pass, fail, cwd)
+  checkRootVitestDevDeps(cwd, pass, fail)
 
   const ignorePaths = await loadCursorIgnorePaths(cwd)
   for (const { rootDir, isComponentLibrary } of vueRoots) {

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

@@ -6,14 +6,14 @@ resource: npm/scripts/lib/fix/
 
 # npm/scripts/lib/fix
 
-| Файл | Тип |
-|---|---|
-| [analyze-escalation.mjs](analyze-escalation.md) | JS Module |
-| [escalation-log.mjs](escalation-log.md) | JS Module |
-| [llm-fix-apply.mjs](llm-fix-apply.md) | JS Module |
-| [llm-lint-fix.mjs](llm-lint-fix.md) | JS Module |
-| [llm-worker.mjs](llm-worker.md) | JS Module |
-| [orchestrator.mjs](orchestrator.md) | JS Module |
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [analyze-escalation.mjs](analyze-escalation.md)       | JS Module |
+| [escalation-log.mjs](escalation-log.md)               | JS Module |
+| [llm-fix-apply.mjs](llm-fix-apply.md)                 | JS Module |
+| [llm-lint-fix.mjs](llm-lint-fix.md)                   | JS Module |
+| [llm-worker.mjs](llm-worker.md)                       | JS Module |
+| [orchestrator.mjs](orchestrator.md)                   | JS Module |
 | [run-conformance-check.mjs](run-conformance-check.md) | JS Module |
-| [t0.mjs](t0.md) | JS Module |
-| [verbose-block.mjs](verbose-block.md) | JS Module |
+| [t0.mjs](t0.md)                                       | JS Module |
+| [verbose-block.mjs](verbose-block.md)                 | JS Module |

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

@@ -3,62 +3,32 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: 08d96254
-  model: claude-sonnet-4-6
+  crc: c34d0630
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Оркеструє повний цикл виправлення порушень конформності: детермінований T0-фікс без LLM → LLM-драбина ескалації (local-min → local-min-retry → cloud-min → cloud-avg) → фінальна перевірка. Кожне провальне правило проходить через тири послідовно до першого зеленого re-check або до обриву (no-key, systemic-помилка, cloud transport fail, вичерпаний avg-кеп).
+## Огляд
 
-## Поведінка
-
-### `buildLadder`
-
-Будує масив рунгів ескалації з чотирьох тирів:
-
-| Тир               | Модель      | Feedback | Timeout                   |
-| ----------------- | ----------- | -------- | ------------------------- |
-| `local-min`       | `LOCAL_MIN` | ні       | `LOCAL_TIMEOUT_MS` (45s)  |
-| `local-min-retry` | `LOCAL_MIN` | так      | `LOCAL_TIMEOUT_MS`        |
-| `cloud-min`       | `CLOUD_MIN` | так      | `CLOUD_TIMEOUT_MS` (120s) |
-| `cloud-avg`       | `CLOUD_AVG` | так      | `CLOUD_TIMEOUT_MS`        |
-
-Рунги з порожньою моделлю (`''`) відфільтровуються — драбина стискається до доступних тирів.
-
-### `escalateRule`
+Модуль відповідає за управління процесом вирішення порушень. Він будує послідовність тирів ескалації за допомогою `buildLadder`. Функція `parseOrchestratorArgs` визначає бюджет LLM та фільтр правил. Далі, `runOrchestratorCli` виконує процес виправлення правил, послідовно застосовуючи `escalateRule` по тирах до досягнення першого успішного вирішення.
 
-Проводить одне правило через драбину до першого зеленого re-check. На кожному рунзі:
-
-1. Виклик `worker.runLlmWorker` (синхронно) з feedback від попереднього рунга.
-2. Re-check через `check([ruleId], cwd)`.
-3. Запис у escalation-лог (`logEscalation`).
-4. Якщо re-check зелений → `{ resolved: true }`.
-5. Якщо ні → `decideAfterFailure` визначає дію: `break` (no-key або cloud transport fail), `skip-model` (systemic omlx-помилка), або продовжити.
-6. Avg-рунг пропускається, якщо `avgBudget <= 0` (з фіксацією у лог).
-
-Після кожного рунга виводить verbose-блок (`printVerboseBlock`), якщо `N_CURSOR_FIX_VERBOSE !== 'off'`.
-
-### `parseOrchestratorArgs`
+## Поведінка
 
-Витягує `--max-avg N` (default: 3) і збирає позиційні аргументи як `ruleFilter`.
+buildLadder будує послідовність тирів ескалації для вирішення порушень.
+escalateRule проходить по послідовності тирів, намагаючись вирішити одне правило до першого успішного перевірки.
+parseOrchestratorArgs парсить аргументи командного рядка для визначення максимального бюджету LLM та фільтра правил.
+runOrchestratorCli виконує повний процес виправлення правил, використовуючи послідовність тирів та бюджет LLM.
 
-### `runOrchestratorCli`
+## Публічний API
 
-Повний цикл:
+buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів. Недоступні рівні ігноруються.
 
-1. Початкова conformance-перевірка → якщо чисто, exit 0.
-2. `runT0Step` — детермінований фікс без LLM; якщо після нього чисто, exit 0.
-3. Для кожного правила, що лишилося — `escalateRule` з відстеженням `avgBudget`.
-4. Фінальна перевірка → exit 0 якщо чисто, exit 1 якщо є невирішені.
+escalateRule — Виконує один етап перевірки за драбиною ескалації. Для кожного кроку викликається модель, відбувається повторна перевірка правила, і результат фіксується в лозі. Процес може зупинитися достроково при певних умовах або після вичерпання ліміту.
 
-## Публічний API
+parseOrchestratorArgs — Витягує максимальне значення для середнього бюджету з аргументів командного рядка та збирає список фільтрів правил.
 
-- `buildLadder({ localMin, cloudMin, cloudAvg })` — повертає масив рунгів ескалації.
-- `escalateRule(rule, cwd, deps)` — проводить одне правило через драбину; `deps` дозволяє ін'єкцію worker/check/clock для тестів; повертає `{ resolved, avgUsed }`.
-- `parseOrchestratorArgs(args)` — повертає `{ maxAvg, ruleFilter }`.
-- `runOrchestratorCli(args, cwd)` — CLI-точка входу; повертає `Promise<0|1>`.
+runOrchestratorCli — Запускає основний процес оркестрації, обробляючи аргументи та керуючи виконанням правил.
 
 ## Гарантії поведінки
 
-- Мутує файли проєкту лише через `worker.runLlmWorker` (apply-changes) і T0-auto.
-- Не кидає винятків назовні: помилки LLM перехоплює worker і повертає як `res.error`.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/fix/orchestrator.mjs

@@ -153,10 +153,6 @@ export async function escalateRule(rule, cwd, deps) {
       log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
     }
 
-    // DEBUG
-    console.error(
-      `[DBG] verbose check: VERBOSE=${env.N_CURSOR_FIX_VERBOSE} promptSummary=${JSON.stringify(res.promptSummary)} reasoning=${res.reasoning}`
-    )
     if (env.N_CURSOR_FIX_VERBOSE !== 'off' && res.promptSummary) {
       printVerboseBlock(rule.ruleId, res.promptSummary, res.reasoning ?? null, res.reasoningSource ?? null)
     }