@nitra/cursor 10.3.0 → 11.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [11.1.0] - 2026-06-15
+
+### Changed
+
+- doc-files lint-крок: opportunistic LLM-fix tier (спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md). У fix-by-default (не `--read-only`) крок тепер не лише детектить застарілі доки, а й намагається їх **згенерувати** локальною моделлю, якщо omlx піднято; недоступний omlx → fix пропускається з повідомленням і лишається exit 1 (гейт тримається, без false-green). `--read-only` (CI/hook) лишається суто детектом — нуль мутацій/LLM. Прапор `meta.json: llmFix:true` (схема `rule-meta.json`) — opt-in лише для контент-правил; логічні лінтери НЕ вмикати (LLM-правка коду може змінити поведінку). Спільне ядро генерації винесено в `runGenerationBatch`/`preflightProblem` (експорт з `docgen-files-batch.mjs`) — перевикористовують і батч-CLI `fix-doc-files`, і lint-крок.
+
+## [11.0.0] - 2026-06-15
+
+### Removed
+
+- CLI: прибрано надлишкові точки входу заради мінімальної поверхні. `lint-ci` видалено — це був чистий аліас `lint --read-only --full` (CI лишається тим самим прапор-комбо). Deprecated-аліас `doc-files <sub>` (`scan|check|gen|stamp`) видалено — 0 живих callerів (hook давно на `lint-doc-files`, скіл на `lint-doc-files`/`fix-doc-files`). Заодно полагоджено застарілу документацію точок входу в `bin/n-cursor.js` (мертві згадки `fix`, опис `lint` → data-driven по `meta.json:lint`) і схему `rule-meta.json` (enum `quick|ci` → `per-file|full`, відповідає реальним значенням і `parseRuleLintSpec`).
+
 ## [10.3.0] - 2026-06-15
 
 ### Added

package/package.json

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

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

@@ -63,7 +63,7 @@ function selectTargets(root, all, { overwrite, retryDegraded }) {
  * Preflight локального бекенда: для omlx-моделі — мінімальний chat-виклик.
  * @returns {string|null} текст фатальної проблеми або null якщо можна генерувати
  */
-function preflightProblem() {
+export function preflightProblem() {
   if (!DEFAULT_LOCAL_MODEL) {
     return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
   }
@@ -214,13 +214,29 @@ export async function runDocFilesGenCli(argv) {
     return 0
   }
 
+  return runGenerationBatch(targets, root, {
+    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`
+  })
+}
+
+/**
+ * Спільне ядро генерації: preflight локального бекенда → послідовний прогін
+ * `targets` через `generateOne` з circuit-breaker'ом (K systemic-збоїв підряд →
+ * abort) → підсумковий звіт. Перевикористовують і батч-CLI (`runDocFilesGenCli`),
+ * і opportunistic lint-крок doc-files (scoped-набір змінених файлів).
+ * @param {Array<object>} targets елементи scanForDocFiles (sourcePath/docPath)
+ * @param {string} root абсолютний корінь
+ * @param {{ headline?: string }} [opts] headline — рядок-шапка прогону у stdout
+ * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
+ */
+export async function runGenerationBatch(targets, root, { headline } = {}) {
   const problem = preflightProblem()
   if (problem) {
     console.error(`✗ fix-doc-files: ${problem}`)
     return 1
   }
 
-  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`)
+  if (headline) console.log(headline)
   const stats = { ok: 0, degraded: 0, err: 0, errors: [], skipped: [] }
 
   let done = 0

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

@@ -9,6 +9,7 @@ import { docPathForSource } from './docgen-scan.mjs'
 import { extractFacts } from './docgen-extract.mjs'
 import { extractAnchors, anchorTokens } from './docgen-extract-anchors.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+import { JUDGE_ENABLED, judgeDoc, judgeFailsDoc } from './docgen-judge.mjs'
 import {
   oneShotMessages,
   sectionMessages,
@@ -449,6 +450,18 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
     }
   }
 
+  // Stage 3 (опц.): семантичний judge-гейт — лише за N_CURSOR_DOCGEN_JUDGE=1 і на
+  // доках, що ПРОЙШЛИ det-скорер (там ховаються false-positives). Scope: inaccurate.
+  let judge = null
+  if (JUDGE_ENABLED && score >= threshold) {
+    try {
+      judge = judgeDoc(src, r.md)
+      if (judgeFailsDoc(judge)) issues = [...issues, `judge:inaccurate:${judge.confidence}`]
+    } catch (error) {
+      issues = [...issues, `judge:error: ${error.message.slice(0, 80)}`]
+    }
+  }
+
   return {
     ...r,
     ms: Date.now() - t0,
@@ -456,7 +469,8 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
     llmCalls: llmMeter.calls,
     score,
     issues,
-    degraded: score < threshold,
+    judge,
+    degraded: score < threshold || judgeFailsDoc(judge),
     model
   }
 }

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

@@ -14,7 +14,7 @@
  *
  * 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 ...
+ *   MEASURE_CACHE=/tmp/x N_CLOUD_MIN_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
@@ -25,7 +25,7 @@ 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 JUDGE_MODEL = env.N_CLOUD_MIN_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)
@@ -48,7 +48,12 @@ function cacheSet(key, val) {
   writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
 }
 
-/** Генерує (з кешем за хешем src). */
+/**
+ * Генерує док (з кешем за хешем src).
+ * @param {string} file абсолютний шлях джерела
+ * @param {string} src вміст файлу
+ * @returns {{md: string, score: number|null, issues: string[], degraded: boolean, cached: boolean}} результат генерації
+ */
 function genCached(file, src) {
   const key = 'gen-' + sha(GEN_MODEL + '\0' + src)
   const hit = cacheGet(key)
@@ -59,7 +64,12 @@ function genCached(file, src) {
   return { ...out, cached: false }
 }
 
-/** Судить (з кешем за хешем src+doc). */
+/**
+ * Судить док сильною моделлю (з кешем за хешем src+doc).
+ * @param {string} src вміст вихідного файлу
+ * @param {string} doc згенерована документація
+ * @returns {{verdict: string, confidence: number, reason: string, offending?: string[], cached: boolean}} verdict судді
+ */
 function judgeCached(src, doc) {
   const key = 'judge-' + sha(JUDGE_MODEL + '\0' + src + '\0' + doc)
   const hit = cacheGet(key)
@@ -67,7 +77,7 @@ function judgeCached(src, doc) {
   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))
+  if (a === -1 || b === -1) 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 }
@@ -85,11 +95,11 @@ function main() {
   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 }
+    try { src = readFileSync(file, 'utf8') } catch (error) { console.error(`[skip] ${tag}: read ${error.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 }
+    try { gen = genCached(file, src) } catch (error) { console.error(`[gen-err] ${tag}: ${error.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: error.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 }
@@ -100,7 +110,7 @@ function main() {
         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)}`) }
+      } catch (error) { row.judgeError = error.message.slice(0, 200); console.error(`  [judge-err] ${error.message.slice(0, 120)}`) }
     }
     rows.push(row)
   }

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

@@ -0,0 +1,72 @@
+/** @see ./docs/docgen-judge.md */
+/**
+ * docgen-judge — опціональний семантичний verdict-гейт (spec
+ * `docs/specs/2026-06-14-docgen-judge-design.md`).
+ *
+ * Доповнює детермінований `scoreDoc`: ловить `inaccurate`-доки (твердження, що
+ * суперечать джерелу), яких структурно-лексичний скорер не бачить у принципі.
+ * Активується АВТОМАТИЧНО, якщо задано `N_CLOUD_MIN_MODEL` (бо суддя потребує
+ * сильнішої за генератор хмарної моделі — без неї судити нема чим). Працює лише на
+ * доках що ПРОЙШЛИ det-скорер (`score ≥ threshold`) — саме там ховаються
+ * false-positives. Scope строго `inaccurate` (вимір показав generic=0%). Без
+ * `N_CLOUD_MIN_MODEL` → 0 змін поведінки. Патерн дзеркалить `scripts/coverage-classify`.
+ */
+import { env } from 'node:process'
+import { callLlm } from '../../../lib/llm.mjs'
+import { CLOUD_MIN } from '../../../lib/models.mjs'
+
+/** Модель-суддя = `N_CLOUD_MIN_MODEL` (хмарний cloud-min tier). */
+export const JUDGE_MODEL = CLOUD_MIN
+/** Гейт активується АВТОМАТИЧНО, коли задано `N_CLOUD_MIN_MODEL` (без нього нема надійного судді). */
+export const JUDGE_ENABLED = Boolean(CLOUD_MIN)
+/** Мін. впевненість, щоб verdict `inaccurate` позначив док як degraded. */
+export const JUDGE_CONFIDENCE = Number(env.N_CURSOR_DOCGEN_JUDGE_THRESHOLD ?? 0.7) || 0.7
+
+const JUDGE_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": vague/boilerplate; could describe almost any file of this kind.
+- "inaccurate": contains at least one claim NOT supported by, or contradicted by, the source code (e.g. wrong return behavior, false "no network"/"read-only", invented symbols/fields).
+Prefer "inaccurate" if any claim is wrong. Respond with ONLY a JSON object, no prose:
+{"verdict":"accurate|generic|inaccurate","confidence":0.0-1.0,"reason":"<10-300 chars>"}`
+
+const VERDICTS = new Set(['accurate', 'generic', 'inaccurate'])
+
+/**
+ * Витягує й валідує verdict-JSON із сирої відповіді LLM (як `parseVerdict` у coverage-classify).
+ * @param {string} rawText сира текстова відповідь судді
+ * @returns {{verdict: string, confidence: number, reason: string}} провалідований verdict
+ * @throws {Error} якщо JSON відсутній/невалідний або не відповідає схемі
+ */
+export function parseDocVerdict(rawText) {
+  const a = rawText.indexOf('{')
+  const b = rawText.lastIndexOf('}')
+  if (a === -1 || b === -1) throw new Error('judge: no JSON object in response')
+  const v = JSON.parse(rawText.slice(a, b + 1))
+  if (!VERDICTS.has(v.verdict)) throw new Error(`judge: bad verdict "${v.verdict}"`)
+  if (typeof v.confidence !== 'number' || v.confidence < 0 || v.confidence > 1) {
+    throw new Error('judge: bad confidence')
+  }
+  return { verdict: v.verdict, confidence: v.confidence, reason: String(v.reason ?? '').slice(0, 500) }
+}
+
+/**
+ * Судить згенерований док сильною моделлю проти джерела.
+ * @param {string} src вміст вихідного файлу
+ * @param {string} doc згенерована документація
+ * @param {{model?: string, timeoutMs?: number}} [opts] override моделі/таймауту
+ * @returns {{verdict: string, confidence: number, reason: string}} verdict судді
+ */
+export function judgeDoc(src, doc, { model = JUDGE_MODEL, timeoutMs = 120_000 } = {}) {
+  const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12_000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
+  const raw = callLlm([{ role: 'system', content: JUDGE_SYSTEM }, { role: 'user', content: user }], model, { timeoutMs, temperature: 0 })
+  return parseDocVerdict(raw)
+}
+
+/**
+ * Чи позначає verdict док як degraded (лише `inaccurate` із достатньою впевненістю).
+ * @param {{verdict: string, confidence: number}|null} verdict verdict судді або null
+ * @returns {boolean} true якщо док треба вважати degraded через семантичну неточність
+ */
+export function judgeFailsDoc(verdict) {
+  return verdict !== null && verdict.verdict === 'inaccurate' && verdict.confidence >= JUDGE_CONFIDENCE
+}

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

@@ -1,7 +1,8 @@
 ---
 docgen:
   source: npm/rules/doc-files/js/docgen-extract.mjs
-  crc: e790ff64
+  crc: a0680e77
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,31 +10,32 @@ docgen:
 
 ## Огляд
 
-Файл витягує факти про конфігурацію та структуру проекту. Визначає мову та заголовок файлу. Витягує публічні експорти та імпорти з різних джерел. Витягує внутрішні та локальні символи. Документація перевіряє наявність операцій запису, обробки помилок, повернення хибних значень при невдачах, мережевих викликів, механізмів кешування та пропуск певних шляхів.
+Витягує структурований факт-лист з вмісту файлів, аналізуючи їх залежно від мови. Для Rust витягує модульний опис, публічні експорти, локальні символи та класифікує імпорти й поведінкові маркери. Для JavaScript/TypeScript/MJS витягує опис, експортовані елементи з JSDoc, класифікує імпорти та визначає поведінкові маркери. При аналізі ігноруються директорії: .github, .git, node_modules, base/, ua/, .firebase. Звертається до мережі та кешує дані протягом одного прогону.
 
 ## Поведінка
 
-1. Витягується факт про файл.
-2. Визначається мова файлу.
-3. Витягується заголовок файлу.
-4. Витягуються публічні експорти.
-5. Витягуються імпорти, класифіковані за джерелом.
-6. Витягуються внутрішні символи, імпортовані з внутрішніх модулів.
-7. Витягуються локальні символи, неекспортовані функції.
-8. Визначаються евристичні маркери.
-    * readOnly: перевірка на наявність операцій запису.
-    * catchesErrors: перевірка на наявність обробки помилок.
-    * returnsFalsyOnFail: перевірка на повернення хибних значень при невдачах.
-    * network: перевірка на наявність мережевих викликів.
-    * caches: перевірка на наявність механізмів кешування.
-    * skips: пропуск шляхів .github, .git, node_modules, base/, ua/, .firebase.
+1. Витягує факт-лист з вмісту файлу.
+2. Визначає мову файлу за розширенням.
+3. Якщо мова — Rust, виконує аналіз Rust-коду:
+    а. Витягує модульний опис з `//!`.
+    б. Визначає публічні експорти (структури, функції, енуми) на основі `pub` префікса або експозиційних атрибутів.
+    в. Визначає локальні (приватні) символи, які не є публічними.
+    г. Класифікує імпорти (`std`, зовнішні, внутрішні).
+    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі специфічних Rust-конструкцій.
+4. Якщо мова — JavaScript/TypeScript/MJS, виконує аналіз JS-коду:
+    а. Витягує загальний опис файлу з верхнього блоку коментарів.
+    б. Витягує експортовані функції та класи разом із їхніми JSDoc-описами.
+    в. Класифікує імпорти на стандартні бібліотеки, NPM-пакети та внутрішні модулі.
+    г. Визначає локальні (неекспортовані) функції та класи.
+    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі евристик.
+5. При аналізі JS-коду, свідомо ігнорує шляхи: .github, .git, node_modules, base/, ua/, .firebase.
+6. Повертає структуру фактів, що містить метадані про файл.
 
 ## Публічний API
 
-extractFacts — код файлу перетворює на список фактів
+extractFacts — витягує факти з вмісту файлу.
 
 ## Гарантії поведінки
 
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Кешує результати в межах одного прогону.
 - Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

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

@@ -0,0 +1,31 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-judge-measure.mjs
+  crc: 7f72e520
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# docgen-judge-measure.mjs
+
+## Огляд
+
+Файл зчитує список файлів для аналізу, спираючись на конфігурацію `report.json`. Для кожного файлу генерується технічна документація за допомогою локальної моделі. Після генерації документація оцінюється хмарною моделлю. Результати оцінки кешуються у межах прогону, а потім збираються у звіт. Звіт зберігається у `report.json` та виводиться у консоль.
+
+## Поведінка
+
+1. Зчитує список файлів для аналізу з командного рядка.
+2. Для кожного файлу зчитує його вміст.
+3. Генерує документацію для файлу, використовуючи локальну модель. Результат кешується за хешем вмісту джерела.
+4. Якщо генерація документації неможлива або не пройшла встановлений поріг якості, фіксує це як помилку або непідтримуваний файл.
+5. Якщо документація пройшла поріг якості, вона передається для оцінки.
+6. Оцінює згенеровану документацію за допомогою потужної хмарної моделі. Результат оцінки кешується за хешем вмісту джерела та документації.
+7. Якщо оцінка неможлива, фіксує помилку оцінки.
+8. Збирає результати для всіх файлів.
+9. Обчислює звіт, включаючи загальну кількість файлів, кількість успішно згенерованих та оцінених, а також відсоток хибнопозитивних результатів (false-positive rate).
+10. Зберігає повний звіт у файл `report.json` у каталозі кешу.
+11. Виводить консольний звіт з ключовими показниками.
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.

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

@@ -0,0 +1,35 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-judge.mjs
+  crc: c6ab093a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# docgen-judge.mjs
+
+## Огляд
+
+Модуль оцінює згенеровану документацію, порівнюючи її з вихідним файлом за допомогою великої мовної моделі. Це дозволяє визначити відповідність та якість документації. Модуль надає функції для запуску оцінки (`judgeDoc`, `judgeFailsDoc`), отримання результатів (`parseDocVerdict`), визначення моделі (`JUDGE_MODEL`), перевірки статусу оцінювача (`JUDGE_ENABLED`) та отримання рівня впевненості (`JUDGE_CONFIDENCE`).
+
+## Поведінка
+
+JUDGE_MODEL — Вказує модель, яку використовує суддя для оцінки документації.
+JUDGE_ENABLED — Позначає, чи активна функціональність судді.
+JUDGE_CONFIDENCE — Визначає мінімальний рівень впевненості, необхідний для позначення документації як деградованої.
+parseDocVerdict — Витягує та валідує об'єкт з оцінкою документації з сирого текстового виводу судді.
+judgeDoc — Виконує оцінку згенерованої документації проти вмісту вихідного файлу за допомогою великої мовної моделі.
+judgeFailsDoc — Визначає, чи слід вважати документацію деградованою на основі оцінки судді.
+
+## Публічний API
+
+JUDGE_MODEL — Визначає модель-суддю як `N_CLOUD_MIN_MODEL` (хмарний мінімальний рівень).
+JUDGE_ENABLED — Автоматично вмикає механізм судді, якщо обрано `N_CLOUD_MIN_MODEL`.
+JUDGE_CONFIDENCE — Встановлює мінімальний рівень впевненості, необхідний для позначення документа як погіршеного (degraded) за неточним вердиктом.
+parseDocVerdict — Витягує та перевіряє структуру вердикту у форматі JSON із сирих даних від великої мовної моделі.
+judgeDoc — Оцінює згенерований документ потужною моделлю, порівнюючи його з вихідним джерелом.
+judgeFailsDoc — Визначає, чи повинен документ бути позначений як погіршений (degraded) на підставі вердикту, якщо він неточний і має достатню впевненість.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -1,7 +1,8 @@
 ---
 docgen:
   source: npm/rules/doc-files/js/docgen-prompts.mjs
-  crc: 72ac304f
+  crc: 28c9e818
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,31 +10,29 @@ docgen:
 
 ## Огляд
 
-Файл надає інструкції для створення лаконічної поведінкової документації українською мовою. Він містить інструменти для формування, перевірки та виправлення тексту документації, а також для визначення гарантій щодо роботи файлу
+Генерує технічну документацію на основі коду. Створює компоненти документації, такі як огляд (`overviewMessages`), повідомлення для секцій (`sectionMessages`), повідомлення для критики (`criticMessages`), повідомлення для уточнення (`refineMessages`) та гарантії, отримані з маркерів (`guaranteesFromMarkers`), застосовуючи заданий стиль (`STYLE`).
 
 ## Поведінка
 
-Поведінка:
-- STYLE: Надає інструкцію для генерації лаконічної поведінкової документації українською мовою.
-- sectionMessages: Генерує секційні промпти для різних частин документації.
-- overviewMessages: Формує текст для узагальнення ролі та призначення файлу.
-- criticMessages: Створює запити для перевірки чорновиків документації на наявність дефектів.
-- refineMessages: Переписує та виправляє чорновки документації відповідно до критики.
-- guaranteesFromMarkers: Формує список гарантій щодо поведінки файлу на основі маркерів.
-- oneShotMessages: Створює універсальний запит для генерації повної документації.
+STYLE: Пише лаконічну поведінкову документацію до коду українською мовою, використовуючи чистий Markdown.
+sectionMessages: Генерує набір промптів для різних секцій документації, використовуючи метадані файлу та вміст коду.
+overviewMessages: Створює узагальнений огляд файлу, базуючись на вже згенерованій секції «Поведінка».
+criticMessages: Перевіряє чорнетку секції на відповідність технічним критеріям, виявляючи дефекти.
+refineMessages: Переписує чорнетку секції, виправляючи дефекти, виявлені критиком.
+guaranteesFromMarkers: Формує список гарантій поведінки, виходячи з машинно-виведених маркерів файлу.
+oneShotMessages: Генерує базовий промпт для генерації повної документації за один виклик.
 
 ## Публічний API
 
-STYLE — Формулює стиль файлу.
-sectionMessages — Збирає повідомлення з мінімальним контекстом для кожної секції.
-overviewMessages — Надає узагальнення поведінки файлу.
-criticMessages — Виявляє дефекти в чорнетці секції.
-refineMessages — Виправляє чорнетку, усуваючи виявлені дефекти.
-guaranteesFromMarkers — Створює детермінований шаблон гарантій поведінки з фактів.
+STYLE — Визначає загальний стиль та намір файлу.
+sectionMessages — Містить мінімально необхідний контекст для кожної секції.
+overviewMessages — Генерує узагальнений огляд на основі вже визначеної поведінки.
+criticMessages — Виявляє конкретні недоліки у чорновому тексті секції, повертаючи список проблем або відсутність проблем.
+refineMessages — Переписує чорновий текст, виправляючи виявлені недоліки.
+guaranteesFromMarkers — Створює чіткий шаблон секції «Гарантії поведінки» на основі фактів.
+oneShotMessages — Надає приклади для порівняння.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

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

@@ -1,5 +1,6 @@
 /**
- * Адаптер агрегатора `n-cursor lint` для правила doc-files.
+ * Адаптер агрегатора `n-cursor lint` для правила doc-files (opportunistic LLM-fix
+ * tier, спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md).
  *
  * Quick-фаза отримує список змінених файлів і мапить їх у пари в **обидва** боки:
  *  - змінене **джерело** (`.js/.mjs/.ts/.vue/.py/.rs`) → перевірка його доки `<dir>/docs/<stem>.md`;
@@ -7,8 +8,11 @@
  *    (той самий stem у каталозі над текою `docs`).
  * Ci-фаза (files === undefined) проганяє повний скан дерева.
  *
- * Порушення — `missing` ∪ `crc-mismatch` (детермінований CRC-детект, 0 LLM-токенів);
- * degraded не блокує. Exit 1 — є stale; 0 — все свіже (конвенція агрегатора).
+ * Детект — `missing` ∪ `crc-mismatch` (детермінований CRC, 0 LLM-токенів); degraded не блокує.
+ * Поведінка за осями (правило має `meta.json: llmFix:true`):
+ *  - `readOnly` (CI/hook): **лише детект** — нуль мутацій/LLM, exit 1 на stale (детермінований гейт);
+ *  - fix-by-default + omlx **піднято**: opportunistic-генерація stale-доків → re-detect → 0 якщо полагоджено;
+ *  - fix-by-default + omlx **недоступно**: fix пропущено (повідомлення) + exit 1 — гейт тримається, без false-green.
  */
 import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
@@ -79,18 +83,34 @@ function reportStale(stale) {
 }
 
 /**
- * Крок агрегатора lint для doc-files.
+ * Збирає застарілі (missing ∪ crc-mismatch) описи у scope кроку.
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
- * @param {string} [cwd] корінь репо
- * @returns {Promise<number>} 0 — OK, 1 — є застарілі доки
+ * @param {string} cwd корінь репо
+ * @returns {Array<{sourcePath:string, docPath:string, reason:string|null}>} stale-описи (готові як targets генерації)
  */
-export function lint(files, cwd = process.cwd()) {
-  if (files === undefined) {
-    const stale = scanForDocFiles(cwd).filter(f => f.stale)
-    return Promise.resolve(reportStale(stale))
-  }
+function collectStale(files, cwd) {
+  if (files === undefined) return scanForDocFiles(cwd).filter(f => f.stale)
   const sources = sourcesFromChanged(files, cwd)
-  if (sources.length === 0) return Promise.resolve(0)
-  const stale = sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
-  return Promise.resolve(reportStale(stale))
+  return sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
+}
+
+/**
+ * Крок агрегатора lint для doc-files (opportunistic LLM-fix tier).
+ * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
+ * @param {string} [cwd] корінь репо
+ * @param {{ readOnly?: boolean }} [opts] readOnly: лише детект (CI/hook), без мутацій/LLM
+ * @returns {Promise<number>} 0 — доки свіжі; 1 — є застарілі (детект, fix пропущено чи помилка генерації)
+ */
+export async function lint(files, cwd = process.cwd(), { readOnly = false } = {}) {
+  const stale = collectStale(files, cwd)
+  if (stale.length === 0) return 0
+  if (readOnly) return reportStale(stale)
+
+  // fix-by-default: opportunistic-генерація через спільне ядро (preflight omlx →
+  // батч із circuit-breaker'ом). omlx недоступний → runGenerationBatch друкує причину
+  // й повертає !=0; ми re-detect'имо й через reportStale віддаємо exit 1 (гейт тримається).
+  process.stdout.write(`ℹ️  doc-files: ${stale.length} застарілих — пробую авто-фікс (omlx)…\n`)
+  const { runGenerationBatch } = await import('./docgen-files-batch.mjs')
+  await runGenerationBatch(stale, cwd, { headline: `📋 doc-files: генерація ${stale.length} файл(ів)` })
+  return reportStale(collectStale(files, cwd))
 }

package/rules/doc-files/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "lint": "per-file" }
+{ "auto": "завжди", "lint": "per-file", "llmFix": true }

package/schemas/rule-meta.json

@@ -11,6 +11,10 @@
       "enum": ["per-file", "full"],
       "description": "Scope lint-кроку: per-file (декомпозиція по змінених файлах, дельта vs origin) або full (нероздільно крос-файловий, лише `lint --full`)."
     },
+    "llmFix": {
+      "type": "boolean",
+      "description": "Opt-in opportunistic LLM-fix: у fix-by-default (не --read-only) lint-крок намагається виправити порушення локальною моделлю (omlx), якщо її піднято; інакше пропускає й лишає exit 1. Лише для контент-правил (doc-files, cspell) — НЕ для логічних лінтерів (зміна коду може змінити поведінку). Деталі: docs/specs/2026-06-15-opportunistic-llm-fix-tier.md."
+    },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",
       "oneOf": [