@nitra/cursor 9.4.0 → 10.0.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [10.0.1] - 2026-06-14
+
+### Changed
+
+- 📝 docs(fix/lint): omlx-генерація доків для нових/перероблених файлів (point 4 docgen)
+
+## [10.0.0] - 2026-06-14
+
+### Changed
+
+- Інлайн _fix-check/fix-t0 у прямі функції — видалено внутрішні subcommand'и. runFixCheck (scripts/lib/fix/run-fix-check) + listProjectRulesMdcFiles винесено з bin; orchestrator/t0/PostToolUse-хук/lint-конформність кличуть прямо (без subprocess-обгортки). Per-rule ізоляція збережена
+
 ## [9.4.0] - 2026-06-14
 
 ### Changed

package/bin/n-cursor.js

@@ -97,8 +97,7 @@ import { readSkillMetaRaw } from '../scripts/lib/skill-meta.mjs'
 import { injectWorktreeNotice } from '../scripts/lib/worktree-notice.mjs'
 import { injectRootNotice } from '../scripts/lib/root-notice.mjs'
 import { runPostToolUseFixCli } from '../scripts/post-tool-use-fix.mjs'
-import { discoverCheckRulesFromCursorRules } from '../scripts/lib/discover-check-rules-from-cursor.mjs'
-import { listRuleIds } from '../scripts/lib/list-rule-ids.mjs'
+import { listProjectRulesMdcFiles } from '../scripts/lib/list-project-rules-mdc.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
 import { assertCwdIsProjectRoot } from '../scripts/lib/assert-project-root.mjs'
 import { runLintDocker } from '../rules/docker/lint/lint.mjs'
@@ -114,8 +113,6 @@ import { runSkillsCli } from '../scripts/skills-cli.mjs'
 import { runWorktreeCli } from '../scripts/worktree-cli.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
 import { runLint } from '../rules/lint/js/orchestrate.mjs'
-import { formatTimingSummary } from '../scripts/lib/timing-summary.mjs'
-import { ensureHkInstall, ensureTool } from '../scripts/lib/ensure-tool.mjs'
 
 const PACKAGE_NAME = '@nitra/cursor'
 const CONFIG_FILE = '.n-cursor.json'
@@ -525,19 +522,6 @@ function formatPiSkillFrontmatter(skillName, descriptionRaw) {
   return `---\nname: ${skillName}\ndescription: >-\n  ${text}\n---\n\n`
 }
 
-/**
- * Повертає відсортовані імена *.mdc у .cursor/rules поточного проєкту
- * @returns {Promise<string[]>} базові імена файлів (лише .mdc)
- */
-async function listProjectRulesMdcFiles() {
-  const rulesDir = join(cwd(), RULES_DIR)
-  if (!existsSync(rulesDir)) {
-    return []
-  }
-  const names = await readdir(rulesDir)
-  return names.filter(n => n.endsWith('.mdc')).toSorted((a, b) => a.localeCompare(b))
-}
-
 /**
  * Базові імена файлів .mdc, які очікуються згідно з .n-cursor.json (префікс n-).
  * @param {string[]} configRules елементи масиву rules з конфігу
@@ -1242,120 +1226,6 @@ function logRemovedManagedItems(title, basePath, names) {
   }
 }
 
-/**
- * Визначає список правил для fix: явно задані (з валідацією проти available) або
- * discovery з `.cursor/rules/*.mdc`. Друкує діагностику й кидає на невідомих правилах.
- * @param {string[]} requestedRules запитані правила (порожній → discovery)
- * @param {string[]} available доступні в пакеті rule-id
- * @param {boolean} json json-режим (впливає на early-return вивід при порожньому discovery)
- * @returns {Promise<string[]|null>} список id або null — нічого запускати (вивід уже зроблено)
- */
-async function resolveFixRuleIds(requestedRules, available, json) {
-  if (requestedRules.length > 0) {
-    const unknown = requestedRules.filter(id => !available.includes(id))
-    if (unknown.length > 0) {
-      console.error(`❌ Невідомі правила: ${unknown.join(', ')}`)
-      console.log(`   Доступні: ${available.join(', ')}`)
-      throw new Error(`Unknown rules: ${unknown.join(', ')}`)
-    }
-    return requestedRules
-  }
-
-  const mdcFiles = await listProjectRulesMdcFiles()
-  if (mdcFiles.length === 0) {
-    throw new Error(
-      `Немає файлів *.mdc у ${RULES_DIR}/. Запустіть \`npx ${PACKAGE_NAME}\` або вкажіть правила: \`npx ${PACKAGE_NAME} fix bun ga\``
-    )
-  }
-  const idsToRun = discoverCheckRulesFromCursorRules(available, mdcFiles)
-  if (idsToRun.length === 0) {
-    if (json) {
-      process.stdout.write(`${JSON.stringify({ total: 0, failed: 0, rules: [] })}\n`)
-      return null
-    }
-    console.log(
-      `\n🔍 ${PACKAGE_NAME} fix — у ${RULES_DIR}/ немає правил з programmatic перевіркою ` +
-        `(відповідного fix.mjs у пакеті). Нічого не запущено.\n`
-    )
-    return null
-  }
-  return idsToRun
-}
-
-/**
- * Прогоняє `fix.mjs` кожного правила окремим процесом; збирає timings і (для json) per-rule output.
- * @param {string[]} idsToRun правила до запуску
- * @param {boolean} json json-режим — захоплює stdout/stderr у структуру замість inherit у термінал
- * @returns {{ totalFailed: number, timings: {id:string, ms:number, ok:boolean}[], ruleResults: {ruleId:string, ok:boolean, output:string}[] }} підсумок прогону
- */
-function runRuleFixProcesses(idsToRun, json) {
-  let totalFailed = 0
-  const timings = []
-  const ruleResults = []
-  for (const id of idsToRun) {
-    const fixPath = join(BUNDLED_RULES_DIR, id, 'fix.mjs')
-    const startedAt = Date.now()
-    const result = json
-      ? spawnSync('bun', [fixPath], { encoding: 'utf8' })
-      : spawnSync('bun', [fixPath], { stdio: 'inherit' })
-    const ok = result.status === 0
-    timings.push({ id: `fix-${id}`, ms: Date.now() - startedAt, ok })
-    if (json) {
-      ruleResults.push({ ruleId: id, ok, output: `${result.stdout ?? ''}${result.stderr ?? ''}`.trim() })
-    }
-    if (!ok) totalFailed++
-  }
-  return { totalFailed, timings, ruleResults }
-}
-
-/**
- * Spawn-wrapper для `npx \@nitra/cursor fix [<rule>...]`. Один шлях у коді: для кожного правила
- * робить `bun rules/<id>/fix.mjs` як окремий процес. Сам `fix.mjs` читає `.n-cursor.json`,
- * перевіряє whitelist (`runRuleCli`) і друкує per-rule summary.
- *
- * Без аргументів — discover з `.cursor/rules/*.mdc` у проекті-споживачі.
- *
- * Серіалізація паралельних запусків — per-rule, всередині `runStandardRule` (`withLock('fix-<id>')`).
- * На рівні `runFixCommand` локу нема: різні набори правил можуть прогресувати незалежно,
- * а однакові правила серіалізуються в spawn'ах нижче.
- * @param {string[]} requestedRules імена правил; порожній масив — discovery з `.cursor/rules/`
- * @param {{json?: boolean}} [opts] json — друкувати компактний JSON `{total, failed, rules:[{ruleId, ok, output}]}`
- *   замість per-rule stdio + timing (для скілу n-fix: агент читає лише впалі правила, не парсить текст)
- * @returns {Promise<void>}
- */
-async function runFixCommand(requestedRules, opts = {}) {
-  const json = opts.json === true
-  // json-режим — діагностичний read-only вивід для скілу: пропускаємо встановлення
-  // git-hook (`ensureHkInstall` друкує «Installed hk hook…» у stdout і забруднив би
-  // чистий JSON; сам pre-commit hook для діагностики не потрібен).
-  const hkBin = ensureTool('hk')
-  if (!json) ensureHkInstall(hkBin)
-  ensureTool('conftest')
-
-  const available = await listRuleIds(BUNDLED_RULES_DIR)
-  if (available.length === 0) {
-    console.error('❌ Не знайдено жодного правила у пакеті')
-    throw new Error('No rules found')
-  }
-
-  // json-режим: захоплюємо stdout/stderr правила у структуру (а не inherit у термінал),
-  // щоб віддати агенту згруповано {ruleId, ok, output} і він читав лише впалі.
-  const idsToRun = await resolveFixRuleIds(requestedRules, available, json)
-  if (idsToRun === null) return
-
-  const { totalFailed, timings, ruleResults } = runRuleFixProcesses(idsToRun, json)
-
-  if (json) {
-    process.stdout.write(`${JSON.stringify({ total: idsToRun.length, failed: totalFailed, rules: ruleResults })}\n`)
-  } else {
-    process.stdout.write(formatTimingSummary('Fix timing', timings))
-  }
-
-  if (totalFailed > 0) {
-    throw new Error(`${totalFailed} з ${idsToRun.length} правил мають проблеми`)
-  }
-}
-
 /**
  * Читає поле `version` з `package.json` пакету за абсолютним шляхом до його кореня.
  * @param {string} packageRoot корінь пакету (тека з `package.json`)
@@ -1643,13 +1513,6 @@ try {
   }
   await ensureNitraCursorInRootDevDependencies(cwd())
   switch (command) {
-    case '_fix-check': {
-      // Внутрішня команда движка конформності (не публічний API): per-rule fix.mjs run() = детект.
-      // Повертає JSON {total, failed, rules:[{ruleId, ok, output}]} у stdout. Викликається
-      // конформність-фазою `lint` (read-only) і движком orchestrator/t0.
-      await runFixCommand(args, { json: true })
-      break
-    }
     case 'rename-yaml-extensions': {
       const code = await runRenameYamlExtensionsCli(args)
       if (code !== 0) {
@@ -1753,16 +1616,6 @@ try {
 
       break
     }
-    case 'fix-t0': {
-      // Внутрішня фаза движка конформності (не публічний API): T0-auto рівень.
-      // Запускає _fix-check, знаходить violation-output із детермінованим паттерном
-      // (vscode-ext-add, rm-forbidden-file тощо), застосовує програмний фікс (0 LLM),
-      // перевіряє check-gate. Викликається orchestrator.mjs (fix-режим конформності lint).
-      const { runT0AutoCli } = await import('../scripts/lib/fix/t0.mjs')
-      process.exitCode = await runT0AutoCli(args, cwd())
-
-      break
-    }
     case 'change': {
       const { runChangeCli } = await import('../rules/release/change.mjs')
       process.exitCode = await runChangeCli(args)

package/package.json

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

package/rules/lint/docs/fix.md

@@ -0,0 +1,27 @@
+---
+docgen:
+  source: npm/rules/lint/fix.mjs
+  crc: f85a9e1d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# fix.mjs
+
+## Огляд
+
+Модуль забезпечує виконання логіки, визначеної правилом. Він ініціює виконання правила через публічну функцію `run`.
+
+## Поведінка
+
+1. Викликати функцію `run` для виконання логіки правила.
+2. Якщо код виконується як CLI, викликати функцію для запуску правила через CLI.
+
+## Публічний API
+
+run — виконує правило `lint` в lint-оркестраторі. Якщо правило не містить перевірок (concern-ів/policy), то `run` не робить нічого (no-op), оскільки не знаходить жодних concern-ів.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -1,7 +1,8 @@
 ---
 docgen:
-  source: rules/lint/js/orchestrate.mjs
-  crc: 34ce8f70
+  source: npm/rules/lint/js/orchestrate.mjs
+  crc: 2e5db1e7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,20 +10,21 @@ docgen:
 
 ## Огляд
 
-Файл оркеструє запуск `n-cursor lint` (quick) або `n-cursor lint-ci` (full). Він збирає налаштування правил з файлів `meta.json` і послідовно виконує перевірку відповідно до визначених режимів.
+Оркестратор `n-cursor lint` визначає, які правила лінтування застосовувати, керуючись двома ортогональними осями: консолідацією правил та уніфікацією режиму `readonly`. Вибір правил відбувається на основі конфігурацій, зокрема файлів `meta.json`, які визначають обсяг дії (`per-file` чи `full`) для кожного правила. Запуск лінтування може сканувати лише змінені файли відносно origin (за замовчуванням) або весь репозиторій при використанні прапорця `--full`.
 
 ## Поведінка
 
-selectLintRules
-Вибирає id правил для фази алфавітним порядком
-
-runLint
-Запускає lint-оркестрацію
+Поведінка
+selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
+runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах, запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
 
 ## Публічний API
 
-selectLintRules — Вибирає ідеальну послідовність правил для фази, упорядковуючи їх за алфавітом.
-runLint — Запускає повний процес перевірки (lint-оркестрацію).
+selectLintRules — Вибирає ідентифікатори правил для контексту в алфавітному порядку.
+runLint — Запускає процес лінтування.
+  full — Сканує весь репозиторій порівняно з початковим станом.
+  readOnly — Виявляє проблеми без внесення змін.
+  rules — Перевіряє лише відповідність заданого набору правил, ігноруючи повне сканування.
 
 ## Гарантії поведінки
 

package/rules/lint/js/orchestrate.mjs

@@ -14,7 +14,6 @@
 import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { spawnSync } from 'node:child_process'
 import { cwd as processCwd } from 'node:process'
 
 import { parseRuleLintSpec, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
@@ -23,7 +22,6 @@ import { collectChangedFilesSince, resolveChangedBase } from '../../../scripts/l
 // Цей файл: npm/rules/lint/js/orchestrate.mjs → PACKAGE_ROOT = npm (чотири dirname угору).
 const PACKAGE_ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
 const RULES_DIR = join(PACKAGE_ROOT, 'rules')
-const N_CURSOR_BIN = join(PACKAGE_ROOT, 'bin', 'n-cursor.js')
 
 /**
  * Конформність-фаза lint (whole-repo: config/file/workflow conformance — те, що раніше робив `fix`).
@@ -41,20 +39,11 @@ async function runConformance(cwd, readOnly, log, filter = []) {
     const { runOrchestratorCli } = await import('../../../scripts/lib/fix/orchestrator.mjs')
     return runOrchestratorCli(filter, cwd)
   }
-  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...filter], { cwd, encoding: 'utf8', timeout: 600_000 })
-  let parsed = null
-  try {
-    parsed = JSON.parse((r.stdout ?? '').trim())
-  } catch {
-    parsed = null
-  }
-  if (!parsed) {
-    log('❌ lint: конформність — помилка перевірки (_fix-check не повернув JSON)\n')
-    return 1
-  }
-  const failed = parsed.rules.filter(/** @param {{ok:boolean}} x */ x => !x.ok)
+  const { runFixCheck } = await import('../../../scripts/lib/fix/run-fix-check.mjs')
+  const { rules } = await runFixCheck(filter, cwd)
+  const failed = rules.filter(x => !x.ok)
   if (failed.length === 0) return 0
-  log(`❌ lint: конформність — ${failed.length} порушень: ${failed.map(/** @param {{ruleId:string}} x */ x => x.ruleId).join(', ')}\n`)
+  log(`❌ lint: конформність — ${failed.length} порушень: ${failed.map(x => x.ruleId).join(', ')}\n`)
   for (const f of failed) if (f.output) log(`${f.output}\n`)
   return 1
 }

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

@@ -0,0 +1,28 @@
+---
+docgen:
+  source: npm/rules/text/lint/cspell-fix.mjs
+  crc: 3ce66d8a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+# cspell-fix.mjs
+
+## Огляд
+
+Модуль інтегрує `cspell` у ланцюжок `lint-text` для виявлення орфографічних помилок. У режимі з можливістю виправлення, процес відбувається шляхом: детект (захоплення виводу) $\rightarrow$ групування знахідок по файлах $\rightarrow$ per-file `omlx-фікс` справжніх помилок (`llmLintFix`) $\rightarrow$ re-detect. У read-only режимі виконується лише детект, що гарантує нуль мутацій. Валідні терміни omlx залишаються, їх ловить повторний `cspell` (далі — у словник `@nitra/cspell-dict`).
+
+## Поведінка
+
+groupFindingsByFile групує вивід `cspell` за файлами, виділяючи знахідки.
+runCspellText запускає `cspell` для виявлення орфографічних помилок, а при вимкненому режимі читання виконує автоматичне виправлення помилок за допомогою зовнішнього інструменту для файлів, що містять справжні помилки, і повторно перевіряє файли.
+
+## Публічний API
+
+groupFindingsByFile — збирає знайдені помилки cspell у групи за файлами.
+runCspellText — виконує перевірку тексту за правилами cspell, застосовуючи автоматичне виправлення від omlx.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/text/lint/docs/lint.md

@@ -1,226 +1,38 @@
 ---
 docgen:
   source: npm/rules/text/lint/lint.mjs
-  crc: bdaef0f8
+  crc: d475ffbb
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-# `lint.mjs` — CLI-обгортка `lint-text`
+# lint.mjs
 
 ## Огляд
 
-Модуль `lint.mjs` — це CLI-обгортка над канонічним підкомандним конвеєром `lint-text` (правило `text.mdc`). Він призначений для запуску ланцюжка лінтерів текстових і конфігураційних артефактів проєкту з автоматичним передвстановленням залежностей та послідовним виконанням кроків з ранньою зупинкою на першій помилці.
+runLintTextCli надає CLI-обгортку для послідовного лінтингу текстових файлів (text.mdc). Обгортка автоматично встановлює необхідні інструменти (`shellcheck`, `dotenv-linter`) через `ensureTool` перед виконанням ланцюжка перевірок. Ланцюжок включає: перевірку правопису (`cspell`), аналіз скриптів (`shellcheck`), перевірку конфігураційних файлів (`dotenv-linter`), форматування Markdown (`markdownlint-cli2`) та валідацію схем (`v8r`). При виявленні першого ненульового коду в ланцюжку, цей код повертається як код виходу, і подальші кроки не виконуються. runLintTextCli експортується для використання як підкоманда `lint-text` з `bin/n-cursor.js`.
 
-Що робить файл:
+## Поведінка
 
-1. Авто-встановлює зовнішні бінарники `shellcheck` і `dotenv-linter` через `ensureTool` (механізм brew/scoop/GitHub Release per-platform).
-2. Перевіряє наявність системного `patch` (необхідний для авто-фіксу `shellcheck`) і друкує install-hint, якщо `patch` відсутній.
-3. Послідовно запускає п'ять кроків лінтінгу:
-   - `cspell .` — перевірка правопису з використанням словника `@nitra/cspell-dict`;
-   - `runShellcheckText()` — авто-фікс і фінальна перевірка `*.sh` через `shellcheck`;
-   - `runDotenvLinter()` — авто-фікс і фінальна перевірка `.env*` через `dotenv-linter`;
-   - `bunx markdownlint-cli2 --fix "**/*.md" "**/*.mdc"` — авто-фікс Markdown;
-   - `runV8rWithGlobs()` — schema-валідація `json/json5/yaml/yml/toml` через `v8r`.
-4. Першу ненульову exit-код у ланцюжку повертає як код виходу всього прогону; наступні кроки не запускаються.
+1. Викликається `runLintTextCli` для запуску процесу лінтингу.
+2. Якщо передано опцію для режиму лише перевірки, всі кроки виконуються без автоматичного виправлення.
+3. Перед виконанням лінтингу автоматично встановлюються необхідні інструменти (`shellcheck`, `dotenv-linter`).
+4. Перевіряється наявність інструменту `patch` для можливого автоматичного виправлення помилок `shellcheck`.
+5. Виконується перевірка правопису за допомогою `cspell`.
+6. Виконується автоматичне виправлення та фінальна перевірка скриптів `.sh` за допомогою `shellcheck`.
+7. Виконується автоматичне виправлення та фінальна перевірка файлів `.env*` за допомогою `dotenv-linter`.
+8. Виконується автоматичне виправлення файлів Markdown (`.md`, `.mdc`) за допомогою `markdownlint-cli2`.
+9. Виконується валідація схем для файлів JSON, JSON5, YAML, YML, TOML за допомогою `v8r`.
+10. Якщо будь-який крок повертає ненульовий код, виконання зупиняється, і повертається код цього першого невдалого кроку.
+11. У разі успішного виконання всіх кроків повертається код 0.
+12. У разі відсутності необхідних бінарників, `runLintTextCli` виводить повідомлення про помилку з інструкціями щодо встановлення (text.mdc).
 
-Призначення preflight-блоку: без авто-встановлення локальний прогін може успішно пройти `cspell` і `markdownlint`, а CI на `ubuntu-latest` (де `shellcheck` є передвстановленим, але `dotenv-linter` — ні) падає на кроці `dotenv-linter` з неінформативним повідомленням. `ensureTool` збирає всі відсутні бінарники до запуску першого кроку.
+## Публічний API
 
-Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) описаний у `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
+runLintTextCli — Виконує лінтинг тексту через командний інтерфейс, синхронізуючи доступ за допомогою блокування та усуваючи дублікати на основі стану Git-дерева. (text.mdc)
 
-## Експорти / API
+## Гарантії поведінки
 
-| Експорт          | Тип                     | Призначення                                                                                                                                                                                                                             |
-| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `runLintTextCli` | `() => Promise<number>` | Публічна CLI-форма команди `lint-text`. Використовується з `bin/n-cursor.js` як підкоманда `lint-text`. Серіалізує виконання через `withLock('lint-text')` і додатково дедуплікує запуски за станом git-дерева через `runStandardLint`. |
-
-Інші ідентифікатори модуля (`PATCH_PREFLIGHT`, `resolvePreflightBin`, `printPreflightMissingMessage`, `preflight`, `runLintTextSteps`) — внутрішні; не експортуються і не призначені для зовнішнього використання.
-
-## Функції
-
-### `resolvePreflightBin(dep)`
-
-Шукає шлях до бінарника `dep.bin` у `PATH`. На Windows (`process.platform === 'win32'`) додатково перебирає альтернативні імена з `dep.winBins` (наприклад, для випадків з `.exe`/`.cmd` варіаціями).
-
-- Сигнатура: `function resolvePreflightBin(dep: PreflightDep): string | null`
-- Параметри:
-  - `dep` — опис залежності з canon-списку preflight-перевірок (тип `PreflightDep`).
-- Повертає: абсолютний шлях до знайденого бінарника або `null`, якщо бінарник не знайдено.
-- Side effects: відсутні (виклик `resolveCmd` лише читає `PATH`, не модифікує процес).
-
-### `printPreflightMissingMessage(dep)`
-
-Друкує stderr-повідомлення про відсутній бінарник: рядок-маркер з іменем, пояснення наслідків, install-команди і посилання на правило `text.mdc`.
-
-- Сигнатура: `function printPreflightMissingMessage(dep: PreflightDep): void`
-- Параметри:
-  - `dep` — опис залежності, джерело пояснення (`dep.explanation`) та install-команд (`dep.install`).
-- Повертає: нічого (`undefined`).
-- Side effects: виводить кілька рядків у `console.error` (stderr). Структура виводу:
-  - `❌ <bin> не знайдено в PATH.`
-  - відступний рядок з `dep.explanation`;
-  - заголовок `   Встанови:`;
-  - по рядку для кожного елемента `dep.install`;
-  - підказку `   Деталі: text.mdc → секція про lint-text.`
-
-### `preflight(dep)`
-
-Виконує preflight-перевірку наявності бінарника й сигналізує результат через консоль.
-
-- Сигнатура: `function preflight(dep: PreflightDep): boolean`
-- Параметри:
-  - `dep` — опис залежності для перевірки в `PATH`.
-- Повертає: `true`, якщо бінарник знайдено; `false`, якщо відсутній.
-- Side effects:
-  - На pass-шляху друкує `dep.successMsg` у `console.log`;
-  - На fail-шляху викликає `printPreflightMissingMessage(dep)` (вивід у `console.error`).
-
-### `runLintTextSteps()`
-
-Внутрішня функція, що послідовно прокручує всі кроки `lint-text` без захоплення локу (лок забезпечується зовнішньою обгорткою `runStandardLint`).
-
-- Сигнатура: `function runLintTextSteps(): number`
-- Параметри: немає.
-- Повертає: `0`, якщо всі кроки успішні; інакше — exit-код першого кроку, що повернув ненульове значення.
-- Алгоритм:
-  1. `ensureTool('shellcheck')` — авто-встановлення `shellcheck`; кидає виключення на провал (поширюється як exit `1` через зовнішній `runStandardLint`).
-  2. `ensureTool('dotenv-linter')` — те саме для `dotenv-linter`.
-  3. `preflight(PATCH_PREFLIGHT)` — hint-only перевірка `patch`; якщо `patch` відсутній — повертає `1` без подальших спроб.
-  4. `runLintStep('cspell', 'npx', ['cspell', '.'])` — `cspell .` через `npx`; ранній return при ненульовому коді.
-  5. Друк заголовку `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` і виклик `runShellcheckText()`; ранній return при ненульовому коді.
-  6. Друк заголовку `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` і виклик `runDotenvLinter()`; ранній return при ненульовому коді.
-  7. `runLintStep('markdownlint', 'bunx', ['markdownlint-cli2', '--fix', '**/*.md', '**/*.mdc'])` — авто-фікс Markdown; ранній return при ненульовому коді.
-  8. Друк заголовку `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` і повернення результату `runV8rWithGlobs()` як підсумкового exit-коду.
-- Side effects: записує лог-рядки у `stdout`; запускає дочірні процеси через `runLintStep` / `ensureTool` / спеціалізовані обгортки; модифікує файлову систему через авто-фікс-кроки (`shellcheck -f diff` + `patch -p1`, `dotenv-linter --fix`, `markdownlint-cli2 --fix`).
-
-### `runLintTextCli` (експорт)
-
-Публічна CLI-форма команди.
-
-- Сигнатура: `const runLintTextCli: () => Promise<number>`
-- Параметри: немає.
-- Повертає: `Promise<number>` — фінальний exit-код прогону (після lock + дедупу).
-- Реалізація: делегує до `runStandardLint(import.meta.dirname, () => runLintTextSteps())`, тобто:
-  - `runStandardLint` бере лок з ім'ям, похідним від директорії скрипту (`import.meta.dirname`);
-  - дедуплікує запуски за станом git-дерева (якщо нічого не змінилося з попереднього успішного прогону — повторного виконання не буде);
-  - всередині локу викликає `runLintTextSteps()`.
-- Side effects: лок-файл, лог-рядки, дочірні процеси (через внутрішній `runLintTextSteps`).
-
-## Типи
-
-### `PreflightDep`
-
-Опис однієї залежності preflight-блоку. Визначений локальним JSDoc `@typedef`-ом.
-
-| Поле          | Тип               | Опис                                                                         |
-| ------------- | ----------------- | ---------------------------------------------------------------------------- |
-| `bin`         | `string`          | Ім'я виконуваного файлу (POSIX-варіант).                                     |
-| `winBins`     | `string[]` (опц.) | Альтернативні імена бінарника на Windows.                                    |
-| `explanation` | `string`          | Наслідки відсутності бінарника (для людино-зрозумілого stderr-повідомлення). |
-| `install`     | `string[]`        | Команди встановлення, по одному рядку на спосіб/платформу.                   |
-| `successMsg`  | `string`          | Повідомлення для `console.log` на pass-шляху preflight.                      |
-
-## Константи
-
-### `PATCH_PREFLIGHT`
-
-Єдиний об'єкт типу `PreflightDep`, що описує системний `patch` як hint-only залежність:
-
-- `bin: 'patch'`;
-- `explanation: 'Без `patch` не застосуються авто-виправлення shellcheck (`shellcheck -f diff`+`patch -p1`).'` (зібраний через `[...].join('\n   ')` з одного елемента; результат — рівно одна логічна підказка з відступом сумісним з шаблоном виводу `printPreflightMissingMessage`);
-- `install`:
-  - `'macOS:         зазвичай уже є в системі'`;
-  - `'Debian/Ubuntu: sudo apt-get install -y patch'`;
-- `successMsg: '✅ patch знайдено в PATH — shellcheck auto-fix працюватиме'`.
-
-`winBins` не задано — на Windows для `patch` шукається лише власне ім'я.
-
-## Залежності
-
-### Зовнішні модулі (Node built-ins)
-
-- `node:process` — імпортується іменована змінна `platform` для детекції Windows у `resolvePreflightBin`.
-
-### Внутрішні модулі (відносні імпорти)
-
-| Модуль                                       | Що використовується                                                                                                                                        |
-| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `../../../scripts/lib/run-lint-step.mjs`     | `runLintStep` — обгортка для запуску одного кроку лінту з префіксованим логом і нормалізованим exit-кодом. Використовується для `cspell` і `markdownlint`. |
-| `../../../scripts/utils/resolve-cmd.mjs`     | `resolveCmd` — пошук бінарника в `PATH`. Викликається з `resolvePreflightBin`.                                                                             |
-| `../../../scripts/lib/run-standard-lint.mjs` | `runStandardLint` — каноном обгортка `lint-*`: серіалізація через `withLock` + дедуп за станом git-дерева. Викликається з `runLintTextCli`.                |
-| `../../../scripts/lib/ensure-tool.mjs`       | `ensureTool` — авто-встановлення бінарників (brew/scoop/GitHub Release). Викликається для `shellcheck` і `dotenv-linter` на початку `runLintTextSteps`.    |
-| `./run-dotenv-linter.mjs`                    | `runDotenvLinter` — авто-фікс + фінальна перевірка `.env*`.                                                                                                |
-| `./run-shellcheck.mjs`                       | `runShellcheckText` — авто-фікс + фінальна перевірка `*.sh` через `shellcheck`.                                                                            |
-| `./run-v8r.mjs`                              | `runV8rWithGlobs` — schema-валідація `json/json5/yaml/yml/toml`.                                                                                           |
-
-### Зовнішні CLI-інструменти (запускаються як дочірні процеси)
-
-- `npx cspell .` — перевірка правопису (зі словником `@nitra/cspell-dict`).
-- `shellcheck` — статичний аналізатор `*.sh` (передвстановлюється `ensureTool`).
-- `dotenv-linter` — лінтер `.env*` (передвстановлюється `ensureTool`).
-- `patch` — потрібен для `shellcheck -f diff | patch -p1` (hint-only, не встановлюється авто).
-- `bunx markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` — авто-фікс Markdown.
-- `v8r` — schema-валідація конфігів (через `runV8rWithGlobs`).
-
-### Правила-довідники
-
-- `.cursor/rules/text.mdc` (`text.mdc`) — канонічний опис набору `lint-text`.
-- `.cursor/rules/scripts.mdc` — секція «Серіалізація важких CLI-команд», що описує патерн `runStandardLint`/`withLock`.
-
-## Потік виконання / Використання
-
-### Виклик з CLI
-
-Файл експортує `runLintTextCli`, який підключається з `bin/n-cursor.js` як підкоманда `lint-text`. Очікувана схема виклику:
-
-```bash
-n-cursor lint-text
-```
-
-Команда повертає exit-код процесу, рівний фінальному коду повернення з `runLintTextCli`.
-
-### Послідовність кроків (happy path)
-
-1. Зовнішній `runStandardLint` намагається взяти лок `lint-text`. Якщо лок вже зайнятий або стан git-дерева не змінився — прогон може дедуплікуватися або зачекати.
-2. Всередині локу викликається `runLintTextSteps()`:
-   1. `ensureTool('shellcheck')` — авто-встановлення (на CI/локально).
-   2. `ensureTool('dotenv-linter')` — те саме.
-   3. `preflight(PATCH_PREFLIGHT)` — друкує `✅ patch знайдено в PATH — shellcheck auto-fix працюватиме` або hint про встановлення.
-   4. `cspell .` — друк префіксованих логів через `runLintStep`.
-   5. `▶ shellcheck (авто-фікс + фінальна перевірка *.sh)` → `runShellcheckText()`.
-   6. `▶ dotenv-linter (авто-фікс + фінальна перевірка .env*)` → `runDotenvLinter()`.
-   7. `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` через `bunx`.
-   8. `▶ v8r (schema-валідація json/json5/yaml/yml/toml)` → `runV8rWithGlobs()`; повертає його результат.
-3. `runStandardLint` повертає підсумковий exit-код як `Promise<number>`.
-
-### Семантика помилок
-
-- Якщо `ensureTool` падає (не вдалося встановити `shellcheck` або `dotenv-linter`) — викидає виключення, яке поширюється з `runLintTextSteps` і обробляється на верхньому рівні (`runStandardLint`) як exit `1`.
-- Якщо `patch` відсутній — `preflight` повертає `false`, `runLintTextSteps` повертає `1` ще до запуску `cspell`.
-- Будь-який наступний крок (`cspell`, `shellcheck`, `dotenv-linter`, `markdownlint`, `v8r`), який повернув ненульовий код, припиняє ланцюжок: цей код повертається з `runLintTextSteps` і далі з `runLintTextCli`.
-
-### Приклад використання у скрипті (Node)
-
-```js
-import { runLintTextCli } from './lint.mjs'
-
-const code = await runLintTextCli()
-process.exit(code)
-```
-
-### Побічні ефекти на файлову систему
-
-Кроки `runShellcheckText`, `runDotenvLinter`, `markdownlint-cli2 --fix` і потенційно `v8r` можуть модифікувати файли (авто-фікс). Це штатна поведінка `lint-text` — після прогону можливі правки в робочому дереві.
-
-## Rebuild Test
-
-З цієї документації можна відновити поведінку модуля:
-
-- Один експорт — асинхронна функція `runLintTextCli()` без параметрів, повертає `Promise<number>` (exit-код).
-- Реалізація `runLintTextCli`: `() => runStandardLint(import.meta.dirname, () => runLintTextSteps())`.
-- `runLintTextSteps()` синхронно:
-  1. викликає `ensureTool('shellcheck')` і `ensureTool('dotenv-linter')`;
-  2. виконує `preflight(PATCH_PREFLIGHT)` і повертає `1`, якщо `patch` відсутній;
-  3. послідовно запускає кроки `cspell` → `runShellcheckText` → `runDotenvLinter` → `markdownlint-cli2 --fix '**/*.md' '**/*.mdc'` → `runV8rWithGlobs`, друкуючи відповідні `▶`-заголовки перед shellcheck/dotenv/v8r;
-  4. ранній return на першому ненульовому коді; інакше повертає результат `runV8rWithGlobs()`.
-- Допоміжні функції: `resolvePreflightBin` (з підтримкою `winBins` на Windows), `printPreflightMissingMessage` (формат stderr-повідомлення), `preflight` (об'єднання resolve+print і друк `successMsg` на pass).
-- Константа `PATCH_PREFLIGHT` з полями `bin/explanation/install/successMsg` (без `winBins`).
-- Залежності: `node:process` (`platform`); локальні модулі `run-lint-step`, `resolve-cmd`, `run-standard-lint`, `ensure-tool`, `run-dotenv-linter`, `run-shellcheck`, `run-v8r`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -0,0 +1,28 @@
+---
+docgen:
+  source: npm/scripts/lib/list-project-rules-mdc.mjs
+  crc: e17e0855
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# list-project-rules-mdc.mjs
+
+## Огляд
+
+Експортує константу CURSOR_RULES_DIR, яка вказує на каталог правил у проєкті-споживачі. Надає функцію для отримання відсортованого списку всіх файлів правил `.mdc` з цього каталогу.
+
+## Поведінка
+
+CURSOR_RULES_DIR — Вказує на каталог правил у проєкті-споживачі.
+listProjectRulesMdcFiles — Повертає відсортований список імен файлів з розширенням `.mdc` у каталозі правил проєкту, або порожній масив, якщо каталог не існує.
+
+## Публічний API
+
+CURSOR_RULES_DIR — Шлях до каталогу правил у проєкті-споживачі.
+listProjectRulesMdcFiles — Збирає список файлів MDC, що містять правила проєкту.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -0,0 +1,31 @@
+---
+docgen:
+  source: npm/scripts/lib/fix/llm-fix-apply.mjs
+  crc: 80befb00
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# llm-fix-apply.mjs
+
+## Огляд
+
+Модуль є спільним ядром для застосування виправлень, згенерованих LLM, використовуючи конформні (`llm-worker.mjs`) та інструментальні (`llm-lint-fix.mjs`) механізми для уникнення дублювання логіки парсингу та застосування змін. Він парсить структуровану відповідь моделі, що містить список змін у форматі `{changes:[{path,content}]}`. Далі, він зчитує вміст файлів, зазначених у цих змінах, та застосовує оновлений вміст до відповідних файлів. Усі операції реалізовані з механізмом fail-safe: при невдачах функції повертають значення помилки (false/null/Err) замість викидання винятків.
+
+## Поведінка
+
+parseChangesResponse парсить сирий текст відповіді моделі, щоб витягнути структуру змін у форматі патчу або повернути null у разі невдачі парсингу.
+readFilesForFix зчитує вміст файлів, зазначених у списку відносних шляхів, відносно кореня проєкту, повертаючи список об'єктів з шляхом та вмістом або null для неіснуючих файлів.
+applyChanges записує нові вмісти в файли, використовуючи наданий список змін, відносно кореня проєкту, повертаючи статус успіху або помилки.
+
+## Публічний API
+
+parseChangesResponse — витягує структуру змін із JSON-відповіді моделі.
+readFilesForFix — зчитує вміст файлів за заданими шляхами для використання у запиті.
+applyChanges — замінює вміст файлів на нові дані, отримані у змінних змін.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -0,0 +1,33 @@
+---
+docgen:
+  source: npm/scripts/lib/fix/llm-lint-fix.mjs
+  crc: de4439e9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+# llm-lint-fix.mjs
+
+## Огляд
+
+Модуль реалізує механізм `omlx-фікс` для обробки знахідок лінтера, що стосуються `detect-only` тулів, які не мають нативного механізму виправлення (відповідно до `lint-orchestrator-fix-readonly`). Він зчитує уражені файли, ініціює запит до моделі через `callLlm` (маршрутизація через `omlx/<model>` з фолбеком каскаду), щоб отримати пропоновані зміни. Ці зміни застосовуються до файлової системи за допомогою спільного ядра `llm-fix-apply`.
+
+## Поведінка
+
+1. Зчитує вміст файлів, зазначених у `filePaths`, використовуючи `projectRoot`.
+2. Формує детальний запит для моделі, включаючи назву тула, інструкцію, сирий вивід знахідок та вміст зчитаних файлів.
+3. Надсилає сформований запит до моделі для отримання виправлень.
+4. Парсить відповідь моделі для вилучення пропонованих змін.
+5. Перевіряє, чи містить відповідь помилку або не містить жодних змін.
+6. Застосовує вилучені зміни до файлової системи, використовуючи `projectRoot`.
+7. Повертає результат виконання `llmLintFix`, що включає статус успіху, можливу помилку або список шляхів, які були успішно виправлені.
+
+## Публічний API
+
+llmLintFix — автоматично виправляє помилки, знайдені лінтером, використовуючи omlx.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Не звертається до мережі.

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

@@ -1,7 +1,8 @@
 ---
 docgen:
-  source: npm/skills/fix/js/llm-worker.mjs
-  crc: 6507b5b7
+  source: npm/scripts/lib/fix/llm-worker.mjs
+  crc: 00730451
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,27 +10,22 @@ docgen:
 
 ## Огляд
 
-MODEL визначає основну модель для виконання операцій. MODEL_HEAVY визначає модель для посиленої обробки. runLlmWorker корегує одне визначене правило порушення через LLM.
+Модуль визначає моделі для стандартних та складних виправлень коду. Він надає функції для ініціалізації моделей (`MODEL`, `MODEL_HEAVY`) та для виконання роботи з мовною моделлю (`runLlmWorker`), застосовуючи згенеровані зміни до файлів проєкту.
 
 ## Поведінка
 
-MODEL
-Визначає модель за замовчуванням для роботи.
-
-MODEL_HEAVY
-Визначає модель для важкої ескалації.
-
-runLlmWorker
-Виправляє одне правило порушення через LLM.
+MODEL визначає модель за замовчуванням для виправлення, використовуючи змінну середовища або значення за замовчуванням.
+MODEL_HEAVY визначає модель для важких виправлень, використовуючи змінну середовища або значення за замовчуванням.
+runLlmWorker виправляє одне правило-порушення, викликаючи LLM для генерації змін, а потім застосовує ці зміни до файлів проєкту.
 
 ## Публічний API
 
-MODEL — Створює модель.
-MODEL_HEAVY — Створює важку модель.
-runLlmWorker — Виправляє одне порушення правила через pi (C1 pattern).
+MODEL — Основна модель для обробки даних.
+MODEL_HEAVY — Важка модель для складних обчислень.
+runLlmWorker — Виправляє одне порушення правила, використовуючи шаблон C1.
 
 ## Гарантії поведінки
 
+- Read-only: файл не виконує операцій запису у файлову систему.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Не звертається до мережі.

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

@@ -1,7 +1,8 @@
 ---
 docgen:
-  source: npm/skills/fix/js/orchestrator.mjs
-  crc: e77aaf7b
+  source: npm/scripts/lib/fix/orchestrator.mjs
+  crc: 3a66072d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,37 +10,19 @@ docgen:
 
 ## Огляд
 
-runOrchestratorCli
-Запускає ітеративний цикл для перевірки набору правил. Проходить через кроки T0-auto та T1, взаємодіючи з LLM-воркерами. Завершує роботу, перевіряючи, чи всі правила виконані, повертаючи нуль або одиницю залежно від кінцевого стану.
+Модуль керує процесом валідації та виправлення правил. Він ініціює перевірку всіх правил. Якщо виявлено порушення, процес ітеративно застосовує детермінований механізм виправлення (T0) та виправлення на основі великої мовної моделі (T1) до невирішених правил. Цей цикл повторюється до досягнення стану, коли всі правила відповідають вимогам, або до перевищення встановленого ліміту ітерацій. Функція `runOrchestratorCli` запускає цей процес.
 
 ## Поведінка
 
-1. Парсинг аргументів
-    Приймає аргументи командного рядка після 'fix'
-    Визначає максимальну кількість ітерацій
-    Визначає фільтр правил
-2. Початкова перевірка
-    Запускає перевірку стану
-    Отримує початковий набір правил
-    Перевіряє наявність помилок
-3. Ітеративний цикл
-    Повторює ітерації до максимального ліміту
-    Виконує крок T0-auto
-    Перевіряє кількість провалів після кроку T0
-    Якщо провалів немає, завершує цикл
-    Виконує крок T1
-    Запускає роботу з LLM-воркерами для кожного правила
-    Збільшує лічильник провалів для невдалих правил
-    Перевіряє стан після LLM
-    Перевіряє наявність невирішених правил
-4. Завершення
-    Перевіряє, чи всі правила вирішено
-    Повертає нуль у разі чистого стану
-    Повертає одиницю у разі невирішеного стану
+1. `runOrchestratorCli` виконує початкову перевірку всіх правил. Якщо порушень немає, процес завершується успішно.
+2. Якщо порушення виявлено, ініціюється ітеративний цикл до максимальної кількості ітерацій.
+3. На кожній ітерації виконується детермінований фікс (крок T0). Це зменшує кількість правил, що потребують подальшої обробки.
+4. Якщо після кроку T0 залишилися невирішені правила, виконується LLM-фікс (крок T1). Для кожного невирішеного правила застосовується відповідна модель, яка може ескалуватися при повторних провалах.
+5. Після LLM-фіксу виконується повторна перевірка всіх правил.
+6. Якщо після перевірки всі правила чисті, процес завершується успішно.
+7. Якщо після завершення всіх ітерацій залишаються невирішені правила, процес завершується з позначкою про невирішені проблеми.
 
 ## Гарантії поведінки
 
 - Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Не звертається до мережі.

package/scripts/lib/fix/docs/run-fix-check.md

@@ -0,0 +1,34 @@
+---
+docgen:
+  source: npm/scripts/lib/fix/run-fix-check.mjs
+  crc: 2a0e5f0a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# run-fix-check.mjs
+
+## Огляд
+
+Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (включаючи завантаження конфігурації, whitelist та ізоляцію від збоїв).
+
+## Поведінка
+
+1. Визначається наявність інструменту `conftest`.
+2. Отримується список усіх доступних ідентифікаторів правил з каталогу правил.
+3. Визначається список ідентифікаторів правил для прогону:
+    а. Якщо надано явний список правил, перевіряється, чи всі ці правила доступні.
+    б. Якщо явний список не надано, скануються файли `.cursor/rules/*.mdc` у корені проєкту. На основі знайдених файлів визначається список правил для прогону.
+4. Якщо визначено ідентифікатори правил для прогону, для кожного ідентифікатора запускається окремий процес `bun` з файлом `fix.mjs` відповідного правила.
+5. Захоплюється вивід кожного процесу.
+6. Підраховується загальна кількість правил, що не пройшли перевірку.
+7. Повертається результат, що містить загальну кількість перевірених правил, кількість невдалих перевірок та детальний список результатів для кожного правила.
+
+## Публічний API
+
+runFixCheck — Визначає відповідність коду заданим правилам, виконуючи перевірку без внесення змін.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -1,37 +1,29 @@
 ---
 docgen:
-  source: npm/skills/fix/js/t0.mjs
-  crc: 51311329
-  score: 90
+  source: npm/scripts/lib/fix/t0.mjs
+  crc: 0321ecc1
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
 # t0.mjs
 
 ## Огляд
 
-applyT0Auto застосовує паттерни T0-auto до вихідного результату.
-
-filterT0AutoRules фільтрує список правил, для яких присутній хоча б один T0-auto паттерн.
-
-runT0AutoCli запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate.
+Модуль керує автоматичним застосуванням паттернів до правил для виправлення виводів порушень. Він визначає, які автоматичні паттерни можуть бути застосовані до правил, використовуючи `filterT0AutoRules`, і запускає повний процес виправлення для всіх відповідних правил через `applyT0Auto` та `runT0AutoCli`. Код працює у режимі fail-safe, перехоплюючи помилки та не викидаючи винятків назовні. Робота модуля залежить від конфігурацій `extensions.json` та `package-lock.json`.
 
 ## Поведінка
 
-applyT0Auto
-Застосовує паттерни T0-auto до одного вихідного результату
-
-filterT0AutoRules
-Фільтрує список правил, для яких існує хоча б один T0-auto паттерн
-
-runT0AutoCli
-Запускає перевірку, застосовує T0-auto до провальних правил, виводить результат та перевіряє стан через check-gate
+Поведінка
+applyT0Auto застосовує визначені автоматичні паттерни до одного виводу порушення, щоб виправити його.
+filterT0AutoRules повертає список ідентифікаторів правил, для яких існують відповідні автоматичні паттерни.
+runT0AutoCli запускає процес виправлення T0-автоматично для всіх провальних правил, застосовуючи паттерни, повторно перевіряючи стан і виводячи підсумок.
 
 ## Публічний API
 
-- applyT0Auto — застосовує всі T0-auto шаблони до одного виводу порушення.
-- filterT0AutoRules — повертає ідентифікатори правил, що мають хоча б один T0-auto шаблон у виводі порушення.
-- runT0AutoCli — виконує команду `n-cursor fix-t0 [правило...]`.
-  - Запускає `fix --json`, застосовує T0-auto до кожного порушення, повторно перевіряє check-gate, виводить звіт.
+applyT0Auto — Впроваджує всі шаблони T0-auto до одного результату виявлених проблем.
+filterT0AutoRules — Визначає, які правила мають хоча б один шаблон T0-auto, виходячи з результату `fix --json`.
+runT0AutoCli — Запускає команду `n-cursor fix-t0 [rule...]`, виконує `fix --json`, застосовує T0-auto до кожної проблеми, повторно перевіряє check-gate та надає звіт.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/orchestrator.mjs

@@ -1,11 +1,7 @@
 /** @see ./docs/orchestrator.md */
 
-import { spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
-import { join } from 'node:path'
-
-const HERE = fileURLToPath(new URL('.', import.meta.url))
-const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
+import { runFixCheck } from './run-fix-check.mjs'
+import { runT0AutoCli } from './t0.mjs'
 
 const DEFAULT_MAX_ITER = 3
 const ESCALATE_AFTER = 2
@@ -29,13 +25,13 @@ function parseOrchestratorArgs(args) {
  * @param {string} cwd корінь проєкту
  * @param {string[]} ruleFilter фільтр правил
  * @param {Array<{ ruleId: string }>} failed правила перед кроком
- * @returns {Array<{ ruleId: string, ok: boolean, output: string }>} правила після T0
+ * @returns {Promise<Array<{ ruleId: string, ok: boolean, output: string }>>} правила після T0
  */
-function runT0Step(cwd, ruleFilter, failed) {
-  spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'pipe' })
+async function runT0Step(cwd, ruleFilter, failed) {
+  await runT0AutoCli([...ruleFilter], cwd)
 
-  const afterT0 = runFixCheck(cwd, ruleFilter)
-  const failedAfterT0 = afterT0?.rules.filter(r => !r.ok) ?? failed
+  const afterT0 = await runFixCheck(ruleFilter, cwd)
+  const failedAfterT0 = afterT0.rules.filter(r => !r.ok)
   const t0Fixed = failed.filter(r => !failedAfterT0.some(f => f.ruleId === r.ruleId))
 
   if (t0Fixed.length > 0) {
@@ -84,12 +80,7 @@ export async function runOrchestratorCli(args, cwd) {
   const failCount = new Map()
 
   // ── Перша перевірка (тихо) ──
-  const initial = runFixCheck(cwd, ruleFilter)
-  if (!initial) {
-    console.error(`❌ fix: помилка перевірки`)
-    return 1
-  }
-
+  const initial = await runFixCheck(ruleFilter, cwd)
   let failed = initial.rules.filter(r => !r.ok)
   const total = initial.total
 
@@ -104,14 +95,14 @@ export async function runOrchestratorCli(args, cwd) {
   if (ruleFilter.length) console.log(`   filter: ${ruleFilter.join(', ')}`)
 
   for (let iter = 1; iter <= maxIter; iter++) {
-    failed = runT0Step(cwd, ruleFilter, failed)
+    failed = await runT0Step(cwd, ruleFilter, failed)
     if (failed.length === 0) break
 
     await runLlmStep(failed, cwd, failCount, worker)
 
     // Перевірка після LLM
-    const afterLLM = runFixCheck(cwd, ruleFilter)
-    failed = afterLLM?.rules.filter(r => !r.ok) ?? failed
+    const afterLLM = await runFixCheck(ruleFilter, cwd)
+    failed = afterLLM.rules.filter(r => !r.ok)
     if (failed.length === 0) break
   }
 
@@ -123,25 +114,3 @@ export async function runOrchestratorCli(args, cwd) {
   console.log(`❌ fix: ${failed.length} невирішених — ${failed.map(r => r.ruleId).join(', ')}`)
   return 1
 }
-
-/**
- * Внутрішня check-gate: запускає fix-перевірки і повертає структурований результат.
- * Не є публічним CLI — викликається лише оркестратором.
- * @param {string}   cwd корінь проєкту
- * @param {string[]} ruleFilter список ID правил (порожній — усі)
- * @returns {{ total: number, failed: number, rules: Array<{ ruleId: string, ok: boolean, output: string }> } | null} JSON-результат або null якщо stdout порожній/невалідний
- */
-function runFixCheck(cwd, ruleFilter = []) {
-  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
-    cwd,
-    encoding: 'utf8',
-    timeout: 120_000
-  })
-  const stdout = r.stdout?.trim()
-  if (!stdout) return null
-  try {
-    return JSON.parse(stdout)
-  } catch {
-    return null
-  }
-}

package/scripts/lib/fix/run-fix-check.mjs

@@ -0,0 +1,76 @@
+/**
+ * Конформність-детект (колишній subcommand `_fix-check`) як ПРЯМА функція — без subprocess-обгортки
+ * `bun n-cursor.js _fix-check`. Викликають конформність-фаза `lint` (read-only), движок
+ * (`orchestrator.mjs`, `t0.mjs`) і PostToolUse-хук.
+ *
+ * Per-rule ізоляція зберігається: кожне `rules/<id>/fix.mjs` усе ще запускається окремим
+ * процесом `bun` (config-loading + whitelist + crash-isolation). Прибрано лише зовнішній
+ * wrapper-subprocess, що його раніше шелили оркестратор/хук.
+ */
+import { spawnSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { cwd as processCwd } from 'node:process'
+
+import { listRuleIds } from '../list-rule-ids.mjs'
+import { ensureTool } from '../ensure-tool.mjs'
+import { discoverCheckRulesFromCursorRules } from '../discover-check-rules-from-cursor.mjs'
+import { listProjectRulesMdcFiles } from '../list-project-rules-mdc.mjs'
+
+// Цей файл: npm/scripts/lib/fix/run-fix-check.mjs → npm/rules (чотири dirname угору + rules).
+const BUNDLED_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
+
+/**
+ * Визначає id правил для прогону: явні (з валідацією) або discovery з `.cursor/rules/*.mdc`.
+ * @param {string[]} requestedRules запитані (порожній → discovery)
+ * @param {string[]} available доступні rule-id у пакеті
+ * @param {string} cwd корінь
+ * @returns {Promise<string[]>} id для прогону (можливо порожній)
+ * @throws {Error} на невідомих явно заданих правилах
+ */
+async function resolveCheckRuleIds(requestedRules, available, cwd) {
+  if (requestedRules.length > 0) {
+    const unknown = requestedRules.filter(id => !available.includes(id))
+    if (unknown.length > 0) throw new Error(`Unknown rules: ${unknown.join(', ')}`)
+    return requestedRules
+  }
+  const mdcFiles = await listProjectRulesMdcFiles(cwd)
+  if (mdcFiles.length === 0) return []
+  return discoverCheckRulesFromCursorRules(available, mdcFiles)
+}
+
+/**
+ * Прогоняє `fix.mjs` кожного правила окремим процесом, захоплюючи output.
+ * @param {string[]} idsToRun правила
+ * @param {string} cwd корінь
+ * @returns {{ totalFailed:number, rules:Array<{ruleId:string, ok:boolean, output:string}> }} результат
+ */
+function runRuleFixProcesses(idsToRun, cwd) {
+  let totalFailed = 0
+  const rules = []
+  for (const id of idsToRun) {
+    const r = spawnSync('bun', [join(BUNDLED_RULES_DIR, id, 'fix.mjs')], { cwd, encoding: 'utf8' })
+    const ok = r.status === 0
+    rules.push({ ruleId: id, ok, output: `${r.stdout ?? ''}${r.stderr ?? ''}`.trim() })
+    if (!ok) totalFailed++
+  }
+  return { totalFailed, rules }
+}
+
+/**
+ * Конформність-детект: per-rule `fix.mjs run()` (= перевірка, без мутацій).
+ * @param {string[]} [requestedRules] фільтр (порожній → discovery з `.cursor/rules/`)
+ * @param {string} [cwd] корінь
+ * @returns {Promise<{ total:number, failed:number, rules:Array<{ruleId:string, ok:boolean, output:string}> }>} результат
+ */
+export async function runFixCheck(requestedRules = [], cwd = processCwd()) {
+  ensureTool('conftest')
+  const available = await listRuleIds(BUNDLED_RULES_DIR)
+  if (available.length === 0) return { total: 0, failed: 0, rules: [] }
+
+  const idsToRun = await resolveCheckRuleIds(requestedRules, available, cwd)
+  if (idsToRun.length === 0) return { total: 0, failed: 0, rules: [] }
+
+  const { totalFailed, rules } = runRuleFixProcesses(idsToRun, cwd)
+  return { total: idsToRun.length, failed: totalFailed, rules }
+}

package/scripts/lib/fix/t0.mjs

@@ -1,8 +1,8 @@
 /** @see ./docs/t0.md */
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { spawnSync } from 'node:child_process'
-import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+import { runFixCheck } from './run-fix-check.mjs'
 
 const REC_REQUIRE_RE = /recommendations має містити "[^"]+"/
 const REC_MATCH_ALL_RE = /recommendations має містити "([^"]+)"/g
@@ -109,27 +109,6 @@ export function filterT0AutoRules(failedRules) {
 
 // ─── CLI entry-point ──────────────────────────────────────────────────────────
 
-const HERE = dirname(fileURLToPath(import.meta.url))
-/** Абсолютний шлях до npm/bin/n-cursor.js відносно цього файлу */
-const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
-
-/**
- * Запускає `_fix-check` і парсить JSON-результат.
- * @param {string[]} ruleFilter список rule-ids (порожній — усі)
- * @param {string}   cwd  корінь проєкту
- * @returns {{ rules: Array<{ ruleId: string, ok: boolean, output: string }> } | { _empty: true } | { _badJson: true }} JSON або маркер помилки
- */
-function fixCheck(ruleFilter, cwd) {
-  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], { cwd, encoding: 'utf8', timeout: 120_000 })
-  const raw = r.stdout?.trim()
-  if (!raw) return { _empty: true, stderr: r.stderr }
-  try {
-    return JSON.parse(raw)
-  } catch {
-    return { _badJson: true }
-  }
-}
-
 /**
  * Застосовує T0-auto до кожного провального правила, розділяючи на applied/skipped.
  * @param {Array<{ ruleId: string, output: string }>} failed провальні правила
@@ -154,26 +133,16 @@ function applyT0ToFailed(failed, cwd) {
  * CLI підкоманда `n-cursor fix-t0 [rule...]`.
  * Запускає `fix --json`, застосовує T0-auto для кожного violation,
  * повторно перевіряє check-gate, виводить підсумок.
- * @param {string[]} args аргументи підкоманди (опційний список rule-ids)
+ * @param {string[]} args аргументи (опційний список rule-ids)
  * @param {string}   cwd  корінь проєкту
  * @returns {Promise<number>} 0 — T0-auto закрив всі або немає порушень; 1 — лишились
  */
-export function runT0AutoCli(args, cwd) {
+export async function runT0AutoCli(args, cwd) {
   const ruleFilter = args.filter(a => !a.startsWith('--'))
   const verbose = args.includes('--verbose') || args.includes('-v')
 
-  // 1. Запустити fix --json
-  const fixJson = fixCheck(ruleFilter, cwd)
-  if (fixJson._empty) {
-    console.error(`n-cursor fix-t0: fix --json повернув порожній stdout`)
-    console.error(fixJson.stderr?.slice(0, 300) ?? '')
-    return 1
-  }
-  if (fixJson._badJson) {
-    console.error(`n-cursor fix-t0: fix --json повернув невалідний JSON`)
-    return 1
-  }
-
+  // 1. Конформність-детект (пряма функція, без subprocess)
+  const fixJson = await runFixCheck(ruleFilter, cwd)
   const failed = fixJson.rules.filter(r => !r.ok)
   if (failed.length === 0) {
     console.log(`✅ fix-t0: всі правила чисті — T0 не потрібен`)
@@ -195,11 +164,7 @@ export function runT0AutoCli(args, cwd) {
   }
 
   // 4. Check-gate: перевірити лише ті правила, що ми чіпали
-  const recheckJson = fixCheck(applied.map(a => a.ruleId), cwd)
-  if (recheckJson._empty) {
-    console.error(`fix-t0: check-gate: fix --json повернув порожній stdout`)
-    return 1
-  }
+  const recheckJson = await runFixCheck(applied.map(a => a.ruleId), cwd)
   const stillFailed = recheckJson.rules.filter(r => !r.ok)
 
   if (verbose) {

package/scripts/lib/list-project-rules-mdc.mjs

@@ -0,0 +1,22 @@
+/**
+ * Список `.mdc`-файлів правил у `.cursor/rules/` проєкту-споживача (відсортований).
+ * Винесено зі `bin/n-cursor.js`, щоб ділити між CLI-dispatch і `run-fix-check` (конформність-детект).
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+/** Каталог правил у проєкті-споживачі (відносно кореня). */
+export const CURSOR_RULES_DIR = '.cursor/rules'
+
+/**
+ * @param {string} [cwd] корінь проєкту
+ * @returns {Promise<string[]>} імена `*.mdc` (відсортовані), або `[]` якщо каталогу немає
+ */
+export async function listProjectRulesMdcFiles(cwd = processCwd()) {
+  const dir = join(cwd, CURSOR_RULES_DIR)
+  if (!existsSync(dir)) return []
+  const names = await readdir(dir)
+  return names.filter(n => n.endsWith('.mdc')).toSorted((a, b) => a.localeCompare(b))
+}

package/scripts/post-tool-use-fix.mjs

@@ -8,11 +8,13 @@
  *
  * Контракт:
  * - stdin Claude Code: JSON із `tool_input.file_path`; якщо файлу немає (напр. Bash) — exit 0 (skip);
- * - інакше spawn `_fix-check` (детект усіх правил), exit-код прозоро пробрасуємо (PostToolUse
- *   не блокує turn, але код лишаємо інформативним: 1 — є порушення конформності).
+ * - інакше пряма `runFixCheck` (детект усіх правил, без subprocess-обгортки), exit-код прозоро:
+ *   1 — є порушення конформності (PostToolUse не блокує turn, але код лишаємо інформативним).
  */
-import { spawn } from 'node:child_process'
 import { once } from 'node:events'
+import { cwd as processCwd } from 'node:process'
+
+import { runFixCheck } from './lib/fix/run-fix-check.mjs'
 
 /**
  * Зчитує stdin до EOF як utf8 рядок. На TTY — повертає `''` одразу.
@@ -57,9 +59,9 @@ export function extractFilePath(stdinJson) {
 /**
  * Точка входу. Викликається з `bin/n-cursor.js` коли argv[0] === `post-tool-use-fix`.
  * Параметри доступні для інʼєкції для тестів: `stdinJson` обходить read від `process.stdin`,
- * `spawnFn` — заміна `node:child_process.spawn`.
- * @param {{ stdinJson?: string, spawnFn?: typeof spawn }} [options] параметри для тестів
- * @returns {Promise<number>} exit code (0 — пропущено / конформність ОК; інше — є порушення)
+ * `runFixCheckFn` — заміна `runFixCheck`.
+ * @param {{ stdinJson?: string, runFixCheckFn?: typeof runFixCheck }} [options] параметри для тестів
+ * @returns {Promise<number>} exit code (0 — пропущено / конформність ОК; 1 — є порушення)
  */
 export async function runPostToolUseFixCli(options = {}) {
   const stdinJson = options.stdinJson ?? (await readStdin())
@@ -68,12 +70,15 @@ export async function runPostToolUseFixCli(options = {}) {
   if (filePath === null) {
     return 0
   }
-  const spawnFn = options.spawnFn ?? spawn
-  // Один read-only виклик: детект конформності всіх активованих правил, без роутингу.
-  const child = spawnFn('npx', ['--no', '@nitra/cursor', '_fix-check'], { stdio: 'inherit' })
+  const check = options.runFixCheckFn ?? runFixCheck
+  // Один read-only детект конформності всіх активованих правил (пряма функція, без subprocess).
   try {
-    const [code] = await once(child, 'exit')
-    return code ?? 1
+    const { failed, rules } = await check([], processCwd())
+    if (failed === 0) return 0
+    for (const r of rules.filter(x => !x.ok)) {
+      if (r.output) process.stderr.write(`${r.output}\n`)
+    }
+    return 1
   } catch (error) {
     process.stderr.write(`post-tool-use-fix: не вдалося запустити детект конформності — ${error.message}\n`)
     return 1