@nitra/cursor 12.7.0 → 12.8.1

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

@@ -64,8 +64,16 @@ function judgeCached(src, 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('}')
+  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 === -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)
@@ -81,17 +89,34 @@ function main() {
     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}`)
+  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 (error) { console.error(`[skip] ${tag}: read ${error.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 (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 }
+    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,9 +125,18 @@ function main() {
     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 (error) { row.judgeError = error.message.slice(0, 200); console.error(`  [judge-err] ${error.message.slice(0, 120)}`) }
+        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 (error) {
+        row.judgeError = error.message.slice(0, 200)
+        console.error(`  [judge-err] ${error.message.slice(0, 120)}`)
+      }
     }
     rows.push(row)
   }
@@ -119,17 +153,26 @@ function main() {
   const report = {
     config: { genModel: GEN_MODEL, judgeModel: JUDGE_MODEL, threshold: THRESHOLD },
     counts: {
-      files: files.length, generated: scored.length,
+      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
+      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)
+    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 })),
+    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
   }
 
@@ -138,10 +181,16 @@ function main() {
   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(
+    `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(
+    `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}`)
 }

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

@@ -58,7 +58,14 @@ export function parseDocVerdict(rawText) {
  */
 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 })
+  const raw = callLlm(
+    [
+      { role: 'system', content: JUDGE_SYSTEM },
+      { role: 'user', content: user }
+    ],
+    model,
+    { timeoutMs, temperature: 0 }
+  )
   return parseDocVerdict(raw)
 }
 

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

@@ -115,9 +115,11 @@ export function scanOrphanedDocs(root) {
     }
   }
 
-  /** Обходить дерево, шукаючи docs/-директорії для orphan-перевірки.
+  /**
+   * Обходить дерево, шукаючи docs/-директорії для orphan-перевірки.
    *  docs/ — входимо завжди (батьківська пройшла ignore-перевірку);
-   *  інші — перевіряємо через isDocgenIgnored. */
+   *  інші — перевіряємо через isDocgenIgnored.
+   */
   function walk(dir) {
     let entries
     try {
@@ -160,7 +162,12 @@ function gitIgnoredPaths(root, relPaths) {
       encoding: 'utf8',
       stdio: ['pipe', 'pipe', 'ignore'] // git пише «not a git repository» у stderr — глушимо
     })
-    return new Set(out.split('\n').map(s => s.trim()).filter(Boolean))
+    return new Set(
+      out
+        .split('\n')
+        .map(s => s.trim())
+        .filter(Boolean)
+    )
   } catch {
     // exit 1 (жоден не ігнорується) і 128 (не git-репо) → execFileSync кидає; обидва = «не фільтруємо».
     return new Set()
@@ -201,7 +208,10 @@ export function scanForDocFiles(root) {
   }
 
   walk(root)
-  const ignored = gitIgnoredPaths(root, results.map(r => r.sourcePath))
+  const ignored = gitIgnoredPaths(
+    root,
+    results.map(r => r.sourcePath)
+  )
   return ignored.size ? results.filter(r => !ignored.has(r.sourcePath)) : results
 }
 

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

@@ -3,28 +3,39 @@ type: JS Module
 title: docgen-crc.mjs
 resource: npm/rules/doc-files/js/docgen-crc.mjs
 docgen:
-  crc: cca0a79f
+  crc: 0c277bb7
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Детермінований маркер актуальності файлових док: контрольна сума джерела у frontmatter плюс опційний degraded-маркер якості. Єдине джерело правди про «дока свіжа/застаріла/неякісна» для генерації, перевірок і хуків.
+## Огляд
+
+Модуль забезпечує роботу з метаданими та оцінкою якості документів. Він дозволяє парсити метадані з Markdown-файлів за допомогою `parseDocFrontmatter`, створювати та заповнювати блоки метаданих за допомогою `buildDocFrontmatter`. Документи можуть бути промарковані за допомогою `stampDoc`. Якість документа оцінюється за допомогою `readDocQuality`, а його актуальність визначається функцією `staleness`, яка використовує `crc32` для перевірки хеш-суми. Модель документа зчитується через `readDocModel`.
 
 ## Поведінка
 
-1. Контрольна сума обчислюється з байтів джерела і записується у машинний frontmatter доки разом зі шляхом джерела; розбіжність суми з поточним джерелом (або відсутність доки) означає застарілість.
-2. Якщо генерація не дотягнула до порогу якості, frontmatter додатково несе оцінку (`score`) і коди проблем (`issues`); коди нормалізуються до YAML-безпечних (без пробілів, обмежена кількість), а старі доки без цих полів лишаються валідними.
-3. Поріг degraded — `70`, override через `N_CURSOR_DOC_FILES_THRESHOLD`.
-4. Перештампування знімає наявний frontmatter і ставить свіжий, не торкаючись тіла документа; якість при цьому передається явно — без неї поля якості зникають.
+QUALITY_THRESHOLD визначає поріг якості, нижче якого дока вважається неякісним.
+crc32 обчислює CRC32 вмісту в hex-форматі.
+parseDocFrontmatter парсить YAML-блок у вмісті md-файлу, виділяючи метадані та тіло.
+buildDocFrontmatter створює OKF-сумісний YAML-блок для доки, включаючи метадані.
+stampDoc замінює або додає свіжий YAML-блок у тіло md-доку, використовуючи дані джерела та оцінку.
+readDocCrc зчитує CRC32 з YAML-блоку md-доки за заданим абсолютним шляхом.
+readDocQuality зчитує оцінку якості (score, issues, retried, judgeModel) з YAML-блоку md-доки за абсолютним шляхом.
+readDocModel зчитує повний ID моделі-генератора з YAML-блоку md-доки за абсолютним шляхом.
+staleness визначає, чи є дока застарілою, порівнюючи CRC джерела з CRC у доці за абсолютними шляхами.
 
 ## Публічний API
 
-- `crc32` — контрольна сума вмісту в hex.
-- `staleness` — стан доки відносно джерела: `missing` / `crc-mismatch` / свіжа.
-- `parseDocFrontmatter` / `buildDocFrontmatter` / `stampDoc` — читання і (пере)штампування машинного блока.
-- `readDocCrc` / `readDocQuality` — точкове читання суми та якості з доки.
-- `QUALITY_THRESHOLD` — чинний поріг degraded.
+QUALITY_THRESHOLD — Визначає рівень якості документа: дока з низьким показником вважається неякісним.
+crc32 — Генерує 32-бітний контрольний сума вмісту у шістнадцятковому форматі.
+parseDocFrontmatter — Витягує метадані з початку документа. Якщо метаданих немає, повертає порожні дані.
+buildDocFrontmatter — Створює блок метаданих, сумісний з OKF, включаючи дані про генерацію документа (CRC, модель, якість).
+stampDoc — Додає метадані до документа, що фіксують його стан.
+readDocCrc — Зчитує контрольний сума з метаданих документа.
+readDocQuality — Зчитує рівень якості, збережений у метаданих документа.
+readDocModel — Зчитує назву моделі, використаної для генерації документа.
+staleness — Визначає, чи є документ актуальним, порівнюючи його з джерелом.
 
 ## Гарантії поведінки
 
-- Сума не залежить від git-стану: rebase, гілки й незакомічені зміни на неї не впливають.
-- Frontmatter — єдиний машинний виняток із правила «чистий Markdown»; тіло доки модуль не редагує.
-- Відсутні поля якості читаються як «не оцінено» (`score: null`), а не як нуль.
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -3,31 +3,33 @@ type: JS Module
 title: docgen-extract.mjs
 resource: npm/rules/doc-files/js/docgen-extract.mjs
 docgen:
-  crc: a0680e77
+  crc: 369662fe
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Витягує структурований факт-лист з вмісту файлів, аналізуючи їх залежно від мови. Для Rust витягує модульний опис, публічні експорти, локальні символи та класифікує імпорти й поведінкові маркери. Для JavaScript/TypeScript/MJS витягує опис, експортовані елементи з JSDoc, класифікує імпорти та визначає поведінкові маркери. При аналізі ігноруються директорії: .github, .git, node_modules, base/, ua/, .firebase. Звертається до мережі та кешує дані протягом одного прогону.
+## Огляд
+
+Модуль витягує структурований факт-лист з вмісту файлів, звертаючись до мережі. Функція `extractFacts` аналізує вміст файлів, визначаючи публічні експорти, локальні символи та поведінкові маркери для Rust та JavaScript/TypeScript файлів. При цьому ігноруються системні та залежності, включаючи каталоги `.github`, `.git`, `node_modules`, `base/`, `ua/` та `.firebase`. Результати аналізу кешуються протягом одного прогону.
 
 ## Поведінка
 
 1. Витягує факт-лист з вмісту файлу.
 2. Визначає мову файлу за розширенням.
 3. Якщо мова — Rust, виконує аналіз Rust-коду:
-    а. Витягує модульний опис з `//!`.
-    б. Визначає публічні експорти (структури, функції, енуми) на основі `pub` префікса або експозиційних атрибутів.
-    в. Визначає локальні (приватні) символи, які не є публічними.
-    г. Класифікує імпорти (`std`, зовнішні, внутрішні).
-    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі специфічних Rust-конструкцій.
+   а. Витягує модульний заголовок (`//!`).
+   б. Визначає публічні експорти (структури, функції, класи), виходячи з префіксів `pub` та атрибутів експозиції.
+   в. Визначає локальні (приватні) символи, які не є публічними.
+   г. Класифікує імпорти (`use`) як стандартні, зовнішні чи внутрішні.
+   д. Визначає поведінкові маркери (наприклад, чи є код лише для читання, чи обробляє помилки).
 4. Якщо мова — JavaScript/TypeScript/MJS, виконує аналіз JS-коду:
-    а. Витягує загальний опис файлу з верхнього блоку коментарів.
-    б. Витягує експортовані функції та класи разом із їхніми JSDoc-описами.
-    в. Класифікує імпорти на стандартні бібліотеки, NPM-пакети та внутрішні модулі.
-    г. Визначає локальні (неекспортовані) функції та класи.
-    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі евристик.
-5. При аналізі JS-коду, свідомо ігнорує шляхи: .github, .git, node_modules, base/, ua/, .firebase.
-6. Повертає структуру фактів, що містить метадані про файл.
+   а. Витягує заголовок файлу.
+   б. Визначає публічні експорти з їхнім JSDoc.
+   в. Класифікує імпорти як стандартні, npm або внутрішні.
+   г. Визначає локальні символи (службові функції).
+   д. Визначає поведінкові маркери (наприклад, чи є код лише для читання, чи звертається до мережі).
+5. Усі аналізи свідомо ігнорують шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.
+6. Повертає структуру фактів, що містить інформацію про файл.
 
 ## Публічний API
 

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

@@ -3,30 +3,30 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: f68c0832
+  crc: 6316eecb
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль керує життєвим циклом документації. Він вибирає цільові документи для оновлення, видаляє непов'язані документи та виконує пакетну генерацію. Модуль забезпечує стійкість роботи, перехоплюючи помилки та не кидаючи винятків назовні. Він також детерміновано оновлює метадані існуючих документів.
+Модуль керує життєвим циклом документації. Він вибирає цілі для оновлення за допомогою `selectTargets`, очищає від неіснуючих джерел за допомогою `purgeOrphanedDocs`, запускає генерацію файлів через `runDocFilesGenCli` та `runDocFilesStampCli`, а також виконує пакетну генерацію за допомогою `runGenerationBatch`. Усі операції виконуються з механізмом перехоплення помилок, що запобігає виникненню винятків назовні.
 
 ## Поведінка
 
-selectTargets фільтрує знайдені файли, вибираючи ті, що застарілі або мають низьку якість і не були спробовані раніше.
-purgeOrphanedDocs видаляє доки, для яких не існує відповідного джерела, і оновлює індекси директорій.
-runDocFilesGenCli ініціює генерацію документації, видаляючи сирітських доків, вибираючи цілі та запускаючи пакетну генерацію.
-runGenerationBatch виконує послідовний прогін цільових файлів, генеруючи документацію та керуючи цим процесом через механізм захисту від збоїв.
-runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих доків, додаючи CRC та зберігаючи якість, без виклику LLM.
+selectTargets відфільтровує документи для генерації, вибираючи застарілі або ті, які мають низьку якість і не були спробовані раніше.
+purgeOrphanedDocs видаляє документи, для яких не існує відповідного джерела, і оновлює індекси директорій.
+runDocFilesGenCli запускає генерацію документації для застарілих або низькоякісних файлів, після попереднього очищення сирітських документів.
+runGenerationBatch виконує послідовну генерацію документації для заданого набору цілей, керуючи процесом через механізм виходу з ладу.
+runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих документів, додаючи CRC та зберігаючи дані про якість.
 
 ## Публічний API
 
-selectTargets — Визначає цілі для генерації: застарілі або погіршені документи, які ще не пройшли перевірку CRC, або всі документи при використанні прапора перезапису.
-purgeOrphanedDocs — Видаляє документи, для яких відсутній вихідний файл, та оновлює/очищає файл `index.md` у відповідній директорії.
+selectTargets — Визначає цілі для генерації документації: застарілі або деградовані документи, або всі документи при використанні прапора перезапису.
+purgeOrphanedDocs — Видаляє документи, для яких відсутній відповідний вихідний файл, та оновлює файл індексу.
 runDocFilesGenCli — Генерує документацію для застарілих або відсутніх документів.
-runGenerationBatch — Виконує послідовну генерацію документів: перевіряє локальний бекенд, обробляє цілі генерації з механізмом захисту від збоїв, і надає фінальний звіт.
-runDocFilesStampCli — Додає або оновлює метадані `source` та `crc` до існуючих документів без залучення великих мовних моделей, використовуючи наявні дані про модель та якість.
+runGenerationBatch — Виконує повний цикл генерації: перевіряє стан локального бекенду, послідовно генерує документи з обробкою збоїв, та створює фінальний звіт.
+runDocFilesStampCli — Додає або оновлює метадані джерела та контрольної суми до існуючих документів без використання великих мовних моделей.
 
 ## Гарантії поведінки
 

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

@@ -3,42 +3,31 @@ type: JS Module
 title: docgen-gen.mjs
 resource: npm/rules/doc-files/js/docgen-gen.mjs
 docgen:
-  crc: 7674d2b2
+  crc: 059d7d6e
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Огляд
-Публічні функції виконують операції з текстом та оцінками. Вони включають виділення коду, вставлення інформації та генерацію документів на основі визначених параметрів.
+## Огляд
 
-## Поведінка
-
-splitProtected
-Вибирає та видаляє код-фенс-обгортку з секції
-
-insertProtected
-Вставляє захищений блок Призначення після заголовка Огляд
+Модуль забезпечує повний цикл роботи з документами: відокремлює захищений блок за допомогою `splitProtected`, вставляє його у визначене місце за допомогою `insertProtected`, генерує повний Markdown-документ через `generateDoc` (з використанням `DEFAULT_LOCAL_MODEL`), а також оцінює якість документа за допомогою `scoreDoc`. Кешування застосовується протягом прогону. (abie.mdc)
 
-scoreDoc
-Перевіряє вихід проти фактів і повертає оцінку та список проблем
-
-DEFAULT_LOCAL_MODEL
-Повертає дефолтну модель для роботи
+## Поведінка
 
-generateDoc
-Генерує документ з детермінованою оцінкою та метаданими
+splitProtected відокремлює захищений блок Призначення від основного документа.
+insertProtected вставляє захищений блок Призначення у фіксовану позицію після заголовка документа.
+scoreDoc оцінює якість згенерованого документа за заданими критеріями.
+DEFAULT_LOCAL_MODEL визначає модель, яка використовується для генерації документа.
+generateDoc генерує повний Markdown-документ з опису файлу, застосовуючи оцінку та можливий ретрай.
 
 ## Публічний API
 
-splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## ` і `###` не обриває блок. (abie.mdc)
-insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція). (abie.mdc)
-scoreDoc — Stage 2.5 — Детермінований скоринг (0 токенів): перевіряє вихід проти фактів. (abie.mdc)
-DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel → omlx напряму. Останній fallback гарантує локальний виклик без змін середовища (через pi CLI той самий локальний виклик виміряно повільніший на ~46%). (abie.mdc)
-generateDoc — Головний API: файл → md-дока з det-оцінкою. (abie.mdc)
+splitProtected — Розділяє захищений розділ `## Призначення` (Варіант B), використовуючи наступний заголовок рівня H2 або H3 як межу.
+insertProtected — Розміщує захищений блок `## Призначення` безпосередньо після основного заголовка (H1).
+scoreDoc — Виконує детерміновану оцінку (Stage 2.5), порівнюючи вихідні дані з фактичною інформацією.
+DEFAULT_LOCAL_MODEL — Визначає модель для генерації документа, використовуючи мінімальну локальну модель. Якщо модель не задана, процес зупиняється з помилкою.
+generateDoc — Основна функція, яка перетворює вхідний файл у Markdown-документ з оцінкою достовірності.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

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

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

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

@@ -3,30 +3,32 @@ type: JS Module
 title: docgen-judge.mjs
 resource: npm/rules/doc-files/js/docgen-judge.mjs
 docgen:
-  crc: c6ab093a
+  crc: fcbf72fa
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль оцінює згенеровану документацію, порівнюючи її з вихідним файлом за допомогою великої мовної моделі. Це дозволяє визначити відповідність та якість документації. Модуль надає функції для запуску оцінки (`judgeDoc`, `judgeFailsDoc`), отримання результатів (`parseDocVerdict`), визначення моделі (`JUDGE_MODEL`), перевірки статусу оцінювача (`JUDGE_ENABLED`) та отримання рівня впевненості (`JUDGE_CONFIDENCE`).
+## Огляд
+
+Модуль реалізує механізм оцінки якості документації. Він визначає модель для оцінки за допомогою `JUDGE_MODEL`, перевіряє статус активності гейту через `JUDGE_ENABLED` та встановлює поріг впевненості за допомогою `JUDGE_CONFIDENCE`. Модуль отримує, парсить та визначає фінальний статус документації, викликаючи `judgeDoc` для отримання висновків, а також може використовувати `judgeFailsDoc` для визначення провалу.
 
 ## Поведінка
 
 JUDGE_MODEL — Вказує модель, яку використовує суддя для оцінки документації.
-JUDGE_ENABLED — Позначає, чи активна функціональність судді.
-JUDGE_CONFIDENCE — Визначає мінімальний рівень впевненості, необхідний для позначення документації як деградованої.
-parseDocVerdict — Витягує та валідує об'єкт з оцінкою документації з сирого текстового виводу судді.
-judgeDoc — Виконує оцінку згенерованої документації проти вмісту вихідного файлу за допомогою великої мовної моделі.
+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) на підставі вердикту, якщо він неточний і має достатню впевненість.
+JUDGE_ENABLED — Автоматично вмикає механізм суддівства, якщо обрано `N_CLOUD_MIN_MODEL`.
+JUDGE_CONFIDENCE — Встановлює мінімальний рівень впевненості для позначення документа як погіршеного (degraded) через неточність.
+parseDocVerdict — Витягує та перевіряє JSON-вердикт із відповіді великої мовної моделі.
+judgeDoc — Оцінює згенерований документ потужною моделлю порівняно з оригінальним джерелом.
+judgeFailsDoc — Визначає, чи повинен документ бути позначений як погіршений, якщо вердикт є `inaccurate` і впевненість достатня.
 
 ## Гарантії поведінки
 

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

@@ -3,47 +3,48 @@ type: JS Module
 title: docgen-scan.mjs
 resource: npm/rules/doc-files/js/docgen-scan.mjs
 docgen:
-  crc: f01465d8
+  crc: 563b7722
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль аналізує кодову базу та пов'язану з нею документацію. Він визначає, які файли є джерелами за допомогою `isSourceFile` та знаходить відповідні шляхи документації за допомогою `docPathForSource`. Модуль перевіряє, чи не залишилися без зв'язку (сиротами) документи, використовуючи `scanOrphanedDocs`, та сканує файли документації за допомогою `scanForDocFiles`. Для роботи з кореневими каталогами використовується `resolveRoot`. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), при цьому при певних збоях повертається `null` замість викидання винятків.
+Модуль визначає, які файли є кодовим джерелом за допомогою `isSourceFile`. Він обчислює відповідні шляхи до Markdown-документів для коду за допомогою `docPathForSource`. Модуль ідентифікує потенційні кандидати для документування за допомогою `isDocCandidate` та надає опис файлу за допомогою `describeFile`. Для аналізу файлової системи використовуються `scanOrphanedDocs` для пошуку "сирітських" документів та `scanForDocFiles` для сканування файлів. Модуль також може визначати кореневий каталог за допомогою `resolveRoot` та виконувати сканування файлів документації через `runDocFilesScanCli` або перевірку через `runDocFilesCheckCli`.
 
 ## Поведінка
 
 isSourceFile визначає, чи є ім'я файлу кодовим джерелом для документування.
-docPathForSource обчислює шлях до відповідного MD-документа для заданого кодового файлу.
-isDocCandidate визначає, чи підлягає певний файл документуванню, враховуючи розширення, статус тесту та ігнорування.
-describeFile описує кодовий файл, надаючи його шлях, шлях до документації та стан застарілості.
-scanOrphanedDocs знаходить MD-документи, які посилаються на кодові файли, що більше не існують.
-scanForDocFiles рекурсивно обходить дерево і повертає список кодових файлів із їхнім станом застарілості, відфільтрований за ігноруванням Git.
-resolveRoot парсить аргументи для визначення абсолютного кореня обходу, використовуючи поточну робочу директорію за замовчуванням.
+docPathForSource обчислює шлях до відповідного md-документа для заданого кодового файлу.
+isDocCandidate визначає, чи є файл кандидатом на документування, враховуючи розширення, статус тесту та ігнорування.
+describeFile описує кодовий файл, надаючи шлях джерела, шлях доки та стан застарілості.
+scanOrphanedDocs знаходить md-документи, які посилаються на джерела, що більше не існують.
+scanForDocFiles рекурсивно сканує дерево і повертає список кодових файлів зі станом застарілості, відфільтрований за ігноруванням Git.
+resolveRoot визначає абсолютний корінь обходу, використовуючи аргументи або поточний робочий каталог.
 runDocFilesScanCli сканує дерево і друкує JSON-масив усіх кодових файлів зі станом застарілості.
-runDocFilesCheckCli виконує перевірку застарілості, підтримуючи режими для перевірки одного файлу, Git-гейту або звітів про знижену якість.
+runDocFilesCheckCli виконує перевірку застарілості, що може бути використана для хуків, Git-гейтів або ручного переліку шляхів.
 
 ## Публічний API
 
-isSourceFile — визначає, чи є файл кодовим джерелом для створення документації.
-docPathForSource — визначає шлях до відповідного MD-документа, розміщений у теці `docs/` відносно коду.
-isDocCandidate — вирішує, чи повинен кодовий файл бути документований: має правильне розширення, не є тестом, не ігнорується та не є системним документом.
-describeFile — надає опис кодового файлу, включаючи його шлях, шлях до документації та статус застарілості.
-scanOrphanedDocs — шукає документи, які посилаються на кодові файли, що більше не існують, перевіряючи лише згенеровані файли.
-scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, визначаючи їхній статус застарілості, і відсіюючи ті, що ігноруються через `.gitignore`.
-resolveRoot — встановлює кореневу директорію для сканування, використовуючи аргумент командного рядка або поточну робочу директорію.
-runDocFilesScanCli — сканує дерево та виводить JSON-масив усіх кодових файлів зі статусом застарілості, дозволяючи фільтрувати лише застарілі або всі файли.
-runDocFilesCheckCli — виконує перевірку застарілості для використання у хуках та командному інтерфейсі.
-
-Режими:
---hook — перевіряє один файл, отриманий з JSON через стандартний ввід.
---git — порівнює файли у `git diff` та блокує процес, якщо знайдено більше за встановлений поріг застарілих файлів.
---degraded — виводить звіт про документи з низьким показником якості.
-<paths…> — обробляє лише вказані шляхи-джерела.
-
-Вихідний код 2 — вказує на знаходження застарілих файлів (для блокування хука).
-Вихідний код 0 — вказує на відсутність застарілих файлів або проходження перевірки згідно з порогом.
+isSourceFile — визначає, чи є файл вихідним кодом для створення документації.
+docPathForSource — визначає шлях до файлу документації, розміщений у теці `docs/` відносно коду.
+isDocCandidate — вирішує, чи повинен кодовий файл бути документований (правильне розширення, не тест, не ігнорується, не системний).
+describeFile — надає опис кодового файлу, включаючи його шлях та статус застарілості.
+scanOrphanedDocs — знаходить файли документації, які посилаються на вихідний код, що більше не існує.
+scanForDocFiles — рекурсивно шукає всі кодові файли у заданому дереві та визначає їхній статус застарілості.
+resolveRoot — встановлює кореневу директорію для сканування, використовуючи аргумент командного рядка або поточну директорію.
+runDocFilesScanCli — сканує дерево та виводить JSON-масив усіх кодових файлів зі статусом застарілості.
+runDocFilesCheckCli — виконує перевірку застарілості файлів для хуків та командного інтерфейсу.
+
+**Режими роботи:**
+`--hook` — перевіряє один файл, отриманий із вхідного JSON, у контексті хука.
+`--git` — порівнює файли у `git diff` та блокує виконання, якщо знайдено застарілі файли, перевищуючи встановлений ліміт.
+`--degraded` — генерує звіт про файли документації, які не відповідають встановленому рівню якості.
+`<paths…>` — обробляє лише вказані явно шляхи-джерела.
+
+**Коди виходу:**
+Вихід 2 — вказує на знаходження застарілих файлів (для блокування хука).
+Вихід 0 — вказує на відсутність застарілих файлів або проходження перевірки згідно з лімітом.
 
 ## Гарантії поведінки