@nitra/cursor 10.0.0 → 10.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [10.1.0] - 2026-06-15
+
+### Changed
+
+- Конформність-селекція: .n-cursor.json — єдине джерело правди. resolveCheckRuleIds бере активні правила прямо з конфіга (available ∩ enabled), .cursor/rules/*.mdc лишається лише fallback'ом коли конфіга нема. Прибрано дрейф «правило enabled, але .mdc нема → тихо пропущено». Per-rule whitelist-гейт у runRuleCli видалено як дубль — гейтинг живе виключно у селекції.
+
+## [10.0.1] - 2026-06-14
+
+### Changed
+
+- 📝 docs(fix/lint): omlx-генерація доків для нових/перероблених файлів (point 4 docgen)
+
 ## [10.0.0] - 2026-06-14
 
 ### Changed

package/package.json

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

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

@@ -0,0 +1,147 @@
+#!/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_CURSOR_DOCGEN_JUDGE_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { generateDoc } from './docgen-gen.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
+import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+
+const env = process.env
+const GEN_MODEL = env.N_LOCAL_MIN_MODEL ?? 'omlx/gemma-4-e4b-it-OptiQ-4bit'
+const JUDGE_MODEL = env.N_CURSOR_DOCGEN_JUDGE_MODEL ?? 'openai-codex/gpt-5.4-mini'
+const THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? QUALITY_THRESHOLD) || 70
+const CACHE_DIR = env.MEASURE_CACHE ?? '/tmp/docgen-judge-measure'
+const JUDGE_TIMEOUT = Number(env.MEASURE_JUDGE_TIMEOUT_MS ?? 120_000)
+
+const SYSTEM = `You are a strict technical-documentation reviewer. You receive a SOURCE file and an auto-generated Markdown DOC describing it. Classify the DOC into exactly one verdict:
+- "accurate": specific to THIS file AND every factual claim is supported by the source.
+- "generic": could describe almost any file of this kind; vague/boilerplate; lacks file-specific substance.
+- "inaccurate": contains at least one claim that is NOT supported by, or is contradicted by, the source code.
+Prefer "inaccurate" over "generic" if any claim is wrong. Respond with ONLY a JSON object, no prose:
+{"verdict":"accurate|generic|inaccurate","confidence":0.0-1.0,"reason":"<20-300 chars>","offending":["<short quote from doc>"]}`
+
+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))
+}
+
+/** Генерує (з кешем за хешем src). */
+function genCached(file, src) {
+  const key = 'gen-' + sha(GEN_MODEL + '\0' + src)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const r = generateDoc(file, { model: GEN_MODEL })
+  const out = { md: r.md, score: r.score, issues: r.issues, degraded: r.degraded }
+  cacheSet(key, out)
+  return { ...out, cached: false }
+}
+
+/** Судить (з кешем за хешем src+doc). */
+function judgeCached(src, doc) {
+  const key = 'judge-' + sha(JUDGE_MODEL + '\0' + src + '\0' + doc)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
+  const raw = callLlm([{ role: 'system', content: SYSTEM }, { role: 'user', content: user }], JUDGE_MODEL, { timeoutMs: JUDGE_TIMEOUT, temperature: 0 })
+  const a = raw.indexOf('{'), b = raw.lastIndexOf('}')
+  if (a < 0 || b < 0) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
+  const v = JSON.parse(raw.slice(a, b + 1))
+  cacheSet(key, v)
+  return { ...v, cached: false }
+}
+
+function main() {
+  const files = process.argv.slice(2).filter(f => !f.startsWith('--'))
+  if (!files.length) {
+    console.error('Usage: node docgen-judge-measure.mjs <file1> <file2> ...')
+    process.exit(2)
+  }
+  console.error(`[measure] gen=${GEN_MODEL} judge=${JUDGE_MODEL} threshold=${THRESHOLD} files=${files.length} cache=${CACHE_DIR}`)
+
+  const rows = []
+  for (const [i, file] of files.entries()) {
+    const tag = `(${i + 1}/${files.length}) ${file}`
+    let src
+    try { src = readFileSync(file, 'utf8') } catch (e) { console.error(`[skip] ${tag}: read ${e.message}`); continue }
+
+    let gen
+    try { gen = genCached(file, src) } catch (e) { console.error(`[gen-err] ${tag}: ${e.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: e.message.slice(0, 200) }); continue }
+    if (gen.score == null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
+
+    const passed = gen.score >= THRESHOLD
+    const row = { file, score: gen.score, degraded: gen.degraded, passed, genCached: gen.cached }
+    console.error(`[gen${gen.cached ? '*' : ''}] ${tag} score=${gen.score} ${passed ? 'PASS' : 'degraded'}`)
+
+    if (passed) {
+      try {
+        const v = judgeCached(src, gen.md)
+        row.verdict = v.verdict; row.confidence = v.confidence; row.reason = v.reason; row.offending = v.offending; row.judgeCached = v.cached
+        console.error(`  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`)
+      } catch (e) { row.judgeError = e.message.slice(0, 200); console.error(`  [judge-err] ${e.message.slice(0, 120)}`) }
+    }
+    rows.push(row)
+  }
+
+  // Aggregate
+  const scored = rows.filter(r => typeof r.score === 'number')
+  const passedRows = scored.filter(r => r.passed && r.verdict)
+  const byVerdict = { accurate: 0, generic: 0, inaccurate: 0 }
+  for (const r of passedRows) byVerdict[r.verdict] = (byVerdict[r.verdict] ?? 0) + 1
+  const M = passedRows.length
+  const bad = byVerdict.generic + byVerdict.inaccurate
+  const pct = n => (M ? ((100 * n) / M).toFixed(1) : '—')
+
+  const report = {
+    config: { genModel: GEN_MODEL, judgeModel: JUDGE_MODEL, threshold: THRESHOLD },
+    counts: {
+      files: files.length, generated: scored.length,
+      unsupported: rows.filter(r => r.unsupported).length,
+      genErrors: rows.filter(r => r.error === 'gen').length,
+      passedDetScorer: scored.filter(r => r.passed).length,
+      judged: M, judgeErrors: rows.filter(r => r.judgeError).length
+    },
+    falsePositiveRate: { // серед PASSED+judged
+      accurate: byVerdict.accurate, generic: byVerdict.generic, inaccurate: byVerdict.inaccurate,
+      badPct: pct(bad), inaccuratePct: pct(byVerdict.inaccurate), genericPct: pct(byVerdict.generic)
+    },
+    offenders: passedRows.filter(r => r.verdict !== 'accurate').map(r => ({ file: r.file, score: r.score, verdict: r.verdict, confidence: r.confidence, reason: r.reason })),
+    rows
+  }
+
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  const out = join(CACHE_DIR, 'report.json')
+  writeFileSync(out, JSON.stringify(report, null, 2))
+
+  console.log('\n===== Q4 MEASUREMENT =====')
+  console.log(`generated: ${report.counts.generated}/${files.length}  (unsupported=${report.counts.unsupported}, gen-errors=${report.counts.genErrors})`)
+  console.log(`passed det-scorer (score≥${THRESHOLD}): ${report.counts.passedDetScorer}   judged: ${M}`)
+  console.log(`among PASSED+judged → accurate=${byVerdict.accurate} generic=${byVerdict.generic} inaccurate=${byVerdict.inaccurate}`)
+  console.log(`>>> det-scorer FALSE-POSITIVE rate: ${pct(bad)}%  (inaccurate=${pct(byVerdict.inaccurate)}%, generic=${pct(byVerdict.generic)}%)`)
+  console.log(`decision guide: <~5% → don't build gate; >~15% → build (inaccurate-only)`)
+  console.log(`report: ${out}`)
+}
+
+main()

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/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/docs/run-rule-cli.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/lib/run-rule-cli.mjs
-  crc: 21a7b19a
+  crc: 264e7ab0
   score: 100
 ---
 
@@ -9,18 +9,15 @@ docgen:
 
 ## Огляд
 
-Файл є автономним CLI-запускачем для одного правила. Він читає конфігурацію з `.n-cursor.json`, перевіряє, чи існує запис для заданого ID у конфігурації, друкує звіт про перевірку та повертає агрегований код виходу.
+Файл є автономним CLI-запускачем для одного правила. Він друкує звіт про перевірку та повертає агрегований код виходу. Whitelist-гейту тут немає: гейтинг активних правил живе виключно у `resolveCheckRuleIds` (селекція за `.n-cursor.json`), а прямий запуск файлу правила — свідома debug/override-дія, тож виконується беззастережно.
 
 ## Поведінка
 
 1.  Викликається для запуску правила.
-2.  Читає конфігурацію з `.n-cursor.json`.
-3.  Перевіряє наявність правила у whitelist.
-4.  Якщо правило не дозволено, друкує повідомлення про пропуск.
-5.  Якщо правило дозволено, друкує повідомлення про перевірку правила.
-6.  Використовує кеш для перевірки.
-7.  Викликає функцію для виконання стандартного правила з кешем.
-8.  Повертає агрегований код виходу.
+2.  Друкує повідомлення про перевірку правила.
+3.  Використовує кеш для перевірки.
+4.  Викликає функцію для виконання стандартного правила з кешем.
+5.  Повертає агрегований код виходу.
 
 ## Гарантії поведінки
 

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,35 @@
+---
+docgen:
+  source: npm/scripts/lib/fix/run-fix-check.mjs
+  crc: 76874730
+  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` (crash-isolation). Селекція активних правил — єдине джерело: `resolveCheckRuleIds` за `.n-cursor.json`; per-rule whitelist у спавнених процесах прибрано як дубль.
+
+## Поведінка
+
+1. Визначається наявність інструменту `conftest`.
+2. Отримується список усіх доступних ідентифікаторів правил з каталогу правил.
+3. Визначається список ідентифікаторів правил для прогону (`resolveCheckRuleIds`), де `.n-cursor.json` — єдине джерело правди:
+    а. Якщо надано явний список правил — він валідується проти доступних і звужується до активних (вимкнене правило не вмикається навіть на явний запит).
+    б. Якщо явного списку нема й конфіг є — беруться активні правила конфіга (`available ∩ enabled`); `.cursor/rules/*.mdc` ігнорується (фікс дрейфу «enabled, але .mdc нема»).
+    в. Якщо конфіга нема (open-by-default debug) — fallback на скан `.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/run-fix-check.mjs

@@ -4,8 +4,11 @@
  * (`orchestrator.mjs`, `t0.mjs`) і PostToolUse-хук.
  *
  * Per-rule ізоляція зберігається: кожне `rules/<id>/fix.mjs` усе ще запускається окремим
- * процесом `bun` (config-loading + whitelist + crash-isolation). Прибрано лише зовнішній
- * wrapper-subprocess, що його раніше шелили оркестратор/хук.
+ * процесом `bun` (crash-isolation). Прибрано лише зовнішній wrapper-subprocess, що його
+ * раніше шелили оркестратор/хук.
+ *
+ * Селекція активних правил — виключно тут (`resolveCheckRuleIds` за `.n-cursor.json`);
+ * per-rule whitelist у спавнених процесах прибрано як дубль (див. `runRuleCli`).
  */
 import { spawnSync } from 'node:child_process'
 import { dirname, join } from 'node:path'
@@ -16,24 +19,42 @@ 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'
+import { isRuleEnabled, readNCursorConfigLite } from '../read-n-cursor-config-lite.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 у пакеті
+ * Визначає id правил для прогону. `.n-cursor.json` — **єдине джерело правди** селекції:
+ *  - явні `requestedRules` — валідуються проти `available`, тоді звужуються до активних
+ *    (явний запит лише фільтрує всередині активних, не вмикає вимкнене правило);
+ *  - без явних і конфіг **є** — беремо саме активні правила конфіга (`available ∩ enabled`).
+ *    Це прибирає дрейф «правило в `.n-cursor.json:rules`, але `.cursor/rules/*.mdc` нема
+ *    (sync не прогнаний) → раніше тихо пропускалось»;
+ *  - без явних і конфіга **нема** — open-by-default debug: fallback на зматеріалізовані
+ *    `.cursor/rules/*.mdc` (єдиний сигнал «що встановлено», коли немає whitelist).
+ *
+ * Per-rule дубль-гейту (`runRuleCli → isRuleEnabled`) більше немає — гейтинг живе лише тут.
+ * @param {string[]} requestedRules запитані (порожній → auto-селекція)
+ * @param {string[]} available доступні rule-id у пакеті (алфавітно)
  * @param {string} cwd корінь
  * @returns {Promise<string[]>} id для прогону (можливо порожній)
  * @throws {Error} на невідомих явно заданих правилах
  */
-async function resolveCheckRuleIds(requestedRules, available, cwd) {
+export async function resolveCheckRuleIds(requestedRules, available, cwd) {
+  const config = await readNCursorConfigLite(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
+    return requestedRules.filter(id => isRuleEnabled(config, id))
   }
+
+  if (config.exists) {
+    return available.filter(id => isRuleEnabled(config, id))
+  }
+
+  // Конфіга нема → fallback на зматеріалізоване (debug / open-by-default).
   const mdcFiles = await listProjectRulesMdcFiles(cwd)
   if (mdcFiles.length === 0) return []
   return discoverCheckRulesFromCursorRules(available, mdcFiles)

package/scripts/lib/run-rule-cli.mjs

@@ -1,14 +1,17 @@
 /**
  * Standalone CLI runner для одного правила. Викликається з `rules/<id>/fix.mjs`
  * у блоці `if (import.meta.main)` — це робить `bun rules/<id>/fix.mjs` повним
- * еквівалентом старого `npx \@nitra/cursor fix <id>`: читає `.n-cursor.json`,
- * перевіряє whitelist, друкує summary, повертає aggregated exit-code.
+ * еквівалентом `npx \@nitra/cursor fix <id>`: друкує summary, повертає aggregated exit-code.
+ *
+ * **Без whitelist-гейту.** Гейтинг активних правил — єдине джерело: `resolveCheckRuleIds`
+ * (`scripts/lib/fix/run-fix-check.mjs`) за `.n-cursor.json`. Прямий `bun rules/<id>/fix.mjs` —
+ * свідомий запуск саме цього правила (debug / override), тож виконується беззастережно;
+ * усі автоматичні шляхи (lint-конформність, orchestrator, t0, hook) уже спавнять лише активні.
  *
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.
  */
 import { basename } from 'node:path'
 
-import { isRuleEnabled, readNCursorConfigLite } from './read-n-cursor-config-lite.mjs'
 import { runStandardRule } from './run-standard-rule.mjs'
 import { getOrCreateWalkCache } from '../utils/walk-cache.mjs'
 
@@ -21,16 +24,10 @@ const PACKAGE_NAME = '@nitra/cursor'
 
 /**
  * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
- * @returns {Promise<number>} 0 — OK або правило не enabled; 1 — порушення
+ * @returns {Promise<number>} 0 — OK; 1 — порушення
  */
 export async function runRuleCli(ruleDir) {
   const ruleId = basename(ruleDir)
-  const config = await readNCursorConfigLite()
-
-  if (!isRuleEnabled(config, ruleId)) {
-    console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — правило не в \`.n-cursor.json:rules\`. Пропущено.\n`)
-    return 0
-  }
 
   console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — перевірка правила\n`)