@nitra/cursor 12.15.0 → 12.16.0

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

@@ -12,8 +12,24 @@ import {
 import { basename, dirname, join, relative } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { classifyOmlxError, preflightLocalModel } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
+
+/**
+ * Класифікує помилку генерації для batch-логіки (замінює `classifyOmlxError` після
+ * pi-міграції — помилки приходять як винятки з generateDoc/pi-one-shot):
+ *   - `permanent` — pre-send guard «Prompt too long» → skip (не ретраїти);
+ *   - `systemic`  — модель/сервер/registry/RAM упали → circuit-breaker abort;
+ *   - `transient` — таймаут (можна було б ретраїти);
+ *   - `infra`     — інше (рахуємо як помилку, але без abort).
+ * @param {string} msg повідомлення помилки
+ * @returns {'permanent'|'systemic'|'transient'|'infra'} клас
+ */
+function classifyDocgenError(msg) {
+  if (/prompt too long|pre-send guard|too long/i.test(msg)) return 'permanent'
+  if (/registry:|session:|не знайдена|memory|enomem|connection refused|econnrefused/i.test(msg)) return 'systemic'
+  if (/timeout|etimedout/i.test(msg)) return 'transient'
+  return 'infra'
+}
 import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from './docgen-scan.mjs'
 
@@ -134,7 +150,7 @@ async function generateOne(file, root, progress, stats) {
     }
     return 'ok'
   } catch (error) {
-    const cls = classifyOmlxError(error.message)
+    const cls = classifyDocgenError(error.message)
     if (cls === 'permanent') {
       stats.skipped.push(file.sourcePath)
       process.stdout.write(`⊘ skip (permanent): ${error.message}\n`)
@@ -307,9 +323,8 @@ export async function runDocFilesGenCli(argv) {
  * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
  */
 export async function runGenerationBatch(targets, root, { headline } = {}) {
-  const problem = preflightLocalModel(DEFAULT_LOCAL_MODEL)
-  if (problem) {
-    console.error(`✗ fix-doc-files: ${problem}`)
+  if (!DEFAULT_LOCAL_MODEL) {
+    console.error('✗ fix-doc-files: локальну модель не задано (N_LOCAL_MIN_MODEL)')
     return 1
   }
 

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

@@ -2,8 +2,8 @@
 import { readFileSync, existsSync } from 'node:fs'
 import { basename } from 'node:path'
 import { env } from 'node:process'
-import { resolveModel } from '../../../lib/models.mjs'
-import { callLlm as callLlmRaw } from '../../../lib/llm.mjs'
+import { resolveModel } from '../../../lib/pi-model-tiers.mjs'
+import { runOneShot } from '../../../lib/pi-one-shot.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from './docgen-scan.mjs'
 import { extractFacts } from './docgen-extract.mjs'
@@ -23,16 +23,25 @@ import {
 let llmMeter = { calls: 0, ms: 0 }
 
 /**
- * Обгортка callLlm з обліком: лічить кількість викликів і сумарний час у них.
- * callLlm синхронний (spawnSync/curl), генерація одного файлу послідовна — лічильник без гонок.
- * Усі виклики `callLlm(...)` у цьому модулі йдуть через неї автоматично (імпорт як callLlmRaw).
- * @param {...any} args ті самі аргументи, що й у callLlm з lib/llm.mjs
- * @returns {string} відповідь моделі
+ * Обгортка LLM-виклику з обліком (тепер async поверх pi-one-shot): лічить кількість
+ * викликів і сумарний час. Генерація одного файлу послідовна — лічильник без гонок.
+ * Зберігає старий інтерфейс accountant'а: повертає рядок-вміст, кидає на помилці.
+ * @param {Array<{role:string,content:string}>} messages чат-повідомлення
+ * @param {string} model model-id (`provider/id`)
+ * @param {{ timeoutMs?: number, caller?: string }} [opts] ліміт/мітка (temperature/maxTokens не підтримуються pi-one-shot)
+ * @returns {Promise<string>} відповідь моделі
  */
-function callLlm(...args) {
+async function callLlm(messages, model, opts = {}) {
   const started = Date.now()
   try {
-    return callLlmRaw(...args)
+    const res = await runOneShot({
+      messages,
+      modelSpec: model,
+      timeoutMs: opts.timeoutMs,
+      caller: opts.caller ?? 'docgen'
+    })
+    if (res.error) throw new Error(res.error)
+    return res.content
   } finally {
     llmMeter.calls += 1
     llmMeter.ms += Date.now() - started
@@ -273,10 +282,12 @@ export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
  * @param {number} timeoutMs ліміт на один виклик
  * @returns {string} фінальний текст секції
  */
-function critiqueRefineSection(sectionKey, draft, facts, anchors, model, timeoutMs) {
-  const critique = callLlm(criticMessages(sectionKey, draft, facts, anchors), model, { timeoutMs }).trim()
+async function critiqueRefineSection(sectionKey, draft, facts, anchors, model, timeoutMs) {
+  const critique = (await callLlm(criticMessages(sectionKey, draft, facts, anchors), model, { timeoutMs })).trim()
   if (!critique || CRITIC_NONE_RE.test(critique) || critique.length < 12) return draft
-  const refined = callLlm(refineMessages(sectionKey, draft, critique, facts, anchors), model, { timeoutMs }).trim()
+  const refined = (
+    await callLlm(refineMessages(sectionKey, draft, critique, facts, anchors), model, { timeoutMs })
+  ).trim()
   return stripSignatures(stripSection(refined)) || draft
 }
 
@@ -301,8 +312,8 @@ function apiNeedsRefine(facts) {
  * @param {{ intent?: string|null }} [opts] захищена секція «Призначення» для збереження
  * @returns {{ md: string }} зібраний документ
  */
-function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS, { intent = null } = {}) {
-  const text = callLlm(oneShotMessages(facts, src), model, { timeoutMs })
+async function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS, { intent = null } = {}) {
+  const text = await callLlm(oneShotMessages(facts, src), model, { timeoutMs })
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
   return { md: insertProtected(md + '\n', intent) }
@@ -339,27 +350,33 @@ function assemble(stem, sections) {
  * @param {{ anchors?: object|null, temperature?: number, intent?: string|null }} [opts] анкори, температура, захищена секція як контекст
  * @returns {{ md: string }} зібраний документ
  */
-function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, temperature = 0.2, intent = null } = {}) {
+async function orchestratedDoc(
+  facts,
+  src,
+  model,
+  timeoutMs,
+  { anchors = null, temperature = 0.2, intent = null } = {}
+) {
   const sections = {}
   const anc = anchors ?? extractAnchors(src)
   // E3: «Гарантії» — детермінований шаблон з markers (0 LLM-запитів, 0 generic-фраз)
   sections.guarantees = guaranteesFromMarkers(facts)
   // Спершу Поведінка (+API) — секції з фактажем
   for (const s of sectionMessages(facts, src, anc, intent)) {
-    let draft = stripSignatures(stripSection(callLlm(s.messages, model, { timeoutMs, temperature })))
+    let draft = stripSignatures(stripSection(await callLlm(s.messages, model, { timeoutMs, temperature })))
     // E2: critique→refine для API, коли всі описи порожні (модель зриває на generic)
     if (s.key === 'api' && apiNeedsRefine(facts)) {
-      draft = critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
+      draft = await critiqueRefineSection(s.key, draft, facts, anc, model, timeoutMs)
     }
     sections[s.key] = draft
   }
   // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
   let overview = stripSignatures(
     stripSection(
-      callLlm(overviewMessages(facts, sections.behavior ?? '', anc, intent), model, { timeoutMs, temperature })
+      await callLlm(overviewMessages(facts, sections.behavior ?? '', anc, intent), model, { timeoutMs, temperature })
     )
   )
-  overview = critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
+  overview = await critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
   sections.overview = overview
   // Варіант B: дослівно повертаємо захищений блок у фіксовану позицію
   return { md: insertProtected(assemble(basename(facts.relPath), sections), intent) }
@@ -398,7 +415,7 @@ export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? resolveModel('mi
  * @param {{ model?: string, threshold?: number, existingMd?: string|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції)
  * @returns {{ md: string, ms: number, llmMs: number, llmCalls: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації (ms — увесь файл; llmMs/llmCalls — лише LLM; решта ms — оркестрація)
  */
-export function generateDoc(
+export async function generateDoc(
   file,
   { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null } = {}
 ) {
@@ -421,8 +438,8 @@ export function generateDoc(
   const intent = existingMd ? splitProtected(existingMd).body : null
   const anchors = facts.unsupported ? null : extractAnchors(src)
   let r = facts.unsupported
-    ? oneShotDoc(facts, src, model, LOCAL_TIMEOUT_MS, { intent })
-    : orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, intent })
+    ? await oneShotDoc(facts, src, model, LOCAL_TIMEOUT_MS, { intent })
+    : await orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, intent })
 
   // unsupported (vue/py до юніт-шару): скорер не застосовний — score=null, не degraded
   if (facts.unsupported) {
@@ -444,7 +461,7 @@ export function generateDoc(
   // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
   if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
     try {
-      const r2 = orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5, intent })
+      const r2 = await orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5, intent })
       const s2 = scoreDoc(r2.md, facts, { anchors, src })
       if (s2.score > score) {
         r = r2
@@ -463,7 +480,7 @@ export function generateDoc(
   let judge = null
   if (JUDGE_ENABLED && score >= threshold) {
     try {
-      judge = { ...judgeDoc(src, r.md), model: JUDGE_MODEL }
+      judge = { ...(await judgeDoc(src, r.md)), model: JUDGE_MODEL }
       if (judgeFailsDoc(judge)) issues = [...issues, `judge:inaccurate:${judge.confidence}`]
     } catch (error) {
       issues = [...issues, `judge:error: ${error.message.slice(0, 80)}`]
@@ -495,7 +512,7 @@ if (isRunAsCli(import.meta.url)) {
   // Зберегти захищену секцію «Призначення», якщо дока вже існує
   const docPath = docPathForSource(file)
   const existingMd = existsSync(docPath) ? readFileSync(docPath, 'utf8') : null
-  const r = generateDoc(file, { model, existingMd })
+  const r = await generateDoc(file, { model, existingMd })
   const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
   process.stderr.write(
     `[local ${r.model}] ${r.ms}ms (llm ${r.llmMs}ms/${r.llmCalls} calls, orch ${r.ms - r.llmMs}ms) / score=${r.score}${r.degraded ? ' DEGRADED' : ''}${issuesTxt}\n`

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

@@ -3,7 +3,7 @@ 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 { runOneShot } from '../../../lib/pi-one-shot.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
 
 const env = process.env
@@ -43,11 +43,11 @@ function cacheSet(key, val) {
  * @param {string} src вміст файлу
  * @returns {{md: string, score: number|null, issues: string[], degraded: boolean, cached: boolean}} результат генерації
  */
-function genCached(file, src) {
+async 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 r = await 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 }
@@ -59,19 +59,22 @@ function genCached(file, src) {
  * @param {string} doc згенерована документація
  * @returns {{verdict: string, confidence: number, reason: string, offending?: string[], cached: boolean}} verdict судді
  */
-function judgeCached(src, doc) {
+async 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(
-    [
+  const res = await runOneShot({
+    messages: [
       { role: 'system', content: SYSTEM },
       { role: 'user', content: user }
     ],
-    JUDGE_MODEL,
-    { timeoutMs: JUDGE_TIMEOUT, temperature: 0 }
-  )
+    modelSpec: JUDGE_MODEL,
+    timeoutMs: JUDGE_TIMEOUT,
+    caller: 'docgen-measure'
+  })
+  if (res.error) throw new Error(res.error)
+  const raw = res.content
   const a = raw.indexOf('{'),
     b = raw.lastIndexOf('}')
   if (a === -1 || b === -1) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
@@ -83,7 +86,7 @@ function judgeCached(src, doc) {
 /**
  *
  */
-function main() {
+async 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> ...')
@@ -106,7 +109,7 @@ function main() {
 
     let gen
     try {
-      gen = genCached(file, src)
+      gen = await 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) })
@@ -124,7 +127,7 @@ function main() {
 
     if (passed) {
       try {
-        const v = judgeCached(src, gen.md)
+        const v = await judgeCached(src, gen.md)
         row.verdict = v.verdict
         row.confidence = v.confidence
         row.reason = v.reason
@@ -195,4 +198,4 @@ function main() {
   console.log(`report: ${out}`)
 }
 
-main()
+await main()

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

@@ -12,8 +12,8 @@
  * `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'
+import { runOneShot } from '../../../lib/pi-one-shot.mjs'
+import { CLOUD_MIN } from '../../../lib/pi-model-tiers.mjs'
 
 /** Модель-суддя = `N_CLOUD_MIN_MODEL` (хмарний cloud-min tier). */
 export const JUDGE_MODEL = CLOUD_MIN
@@ -56,17 +56,19 @@ export function parseDocVerdict(rawText) {
  * @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 } = {}) {
+export async 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(
-    [
+  const res = await runOneShot({
+    messages: [
       { role: 'system', content: JUDGE_SYSTEM },
       { role: 'user', content: user }
     ],
-    model,
-    { timeoutMs, temperature: 0 }
-  )
-  return parseDocVerdict(raw)
+    modelSpec: model,
+    timeoutMs,
+    caller: 'docgen-judge'
+  })
+  if (res.error) throw new Error(res.error)
+  return parseDocVerdict(res.content)
 }
 
 /**

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

@@ -3,29 +3,12 @@ type: JS Module
 title: docgen-files-batch.mjs
 resource: npm/rules/doc-files/js/docgen-files-batch.mjs
 docgen:
-  crc: 6316eecb
+  crc: 26217123
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-Модуль керує життєвим циклом документації. Він вибирає цілі для оновлення за допомогою `selectTargets`, очищає від неіснуючих джерел за допомогою `purgeOrphanedDocs`, запускає генерацію файлів через `runDocFilesGenCli` та `runDocFilesStampCli`, а також виконує пакетну генерацію за допомогою `runGenerationBatch`. Усі операції виконуються з механізмом перехоплення помилок, що запобігає виникненню винятків назовні.
-
-## Поведінка
-
-selectTargets відфільтровує документи для генерації, вибираючи застарілі або ті, які мають низьку якість і не були спробовані раніше.
-purgeOrphanedDocs видаляє документи, для яких не існує відповідного джерела, і оновлює індекси директорій.
-runDocFilesGenCli запускає генерацію документації для застарілих або низькоякісних файлів, після попереднього очищення сирітських документів.
-runGenerationBatch виконує послідовну генерацію документації для заданого набору цілей, керуючи процесом через механізм виходу з ладу.
-runDocFilesStampCli детерміновано оновлює метадані (frontmatter) існуючих документів, додаючи CRC та зберігаючи дані про якість.
-
-## Публічний API
-
-selectTargets — Визначає цілі для генерації документації: застарілі або деградовані документи, або всі документи при використанні прапора перезапису.
-purgeOrphanedDocs — Видаляє документи, для яких відсутній відповідний вихідний файл, та оновлює файл індексу.
-runDocFilesGenCli — Генерує документацію для застарілих або відсутніх документів.
-runGenerationBatch — Виконує повний цикл генерації: перевіряє стан локального бекенду, послідовно генерує документи з обробкою збоїв, та створює фінальний звіт.
-runDocFilesStampCli — Додає або оновлює метадані джерела та контрольної суми до існуючих документів без використання великих мовних моделей.
-
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -3,29 +3,12 @@ type: JS Module
 title: docgen-gen.mjs
 resource: npm/rules/doc-files/js/docgen-gen.mjs
 docgen:
-  crc: 059d7d6e
+  crc: 2d3245b9
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 50
+  issues: no-overview,short-behavior,anchor-miss:(abie.mdc),best-of-2:retry-lost
 ---
 
-Модуль забезпечує повний цикл роботи з документами: відокремлює захищений блок за допомогою `splitProtected`, вставляє його у визначене місце за допомогою `insertProtected`, генерує повний Markdown-документ через `generateDoc` (з використанням `DEFAULT_LOCAL_MODEL`), а також оцінює якість документа за допомогою `scoreDoc`. Кешування застосовується протягом прогону. (abie.mdc)
-
-## Поведінка
-
-splitProtected відокремлює захищений блок Призначення від основного документа.
-insertProtected вставляє захищений блок Призначення у фіксовану позицію після заголовка документа.
-scoreDoc оцінює якість згенерованого документа за заданими критеріями.
-DEFAULT_LOCAL_MODEL визначає модель, яка використовується для генерації документа.
-generateDoc генерує повний Markdown-документ з опису файлу, застосовуючи оцінку та можливий ретрай.
-
-## Публічний API
-
-splitProtected — Розділяє захищений розділ `## Призначення` (Варіант B), використовуючи наступний заголовок рівня H2 або H3 як межу.
-insertProtected — Розміщує захищений блок `## Призначення` безпосередньо після основного заголовка (H1).
-scoreDoc — Виконує детерміновану оцінку (Stage 2.5), порівнюючи вихідні дані з фактичною інформацією.
-DEFAULT_LOCAL_MODEL — Визначає модель для генерації документа, використовуючи мінімальну локальну модель. Якщо модель не задана, процес зупиняється з помилкою.
-generateDoc — Основна функція, яка перетворює вхідний файл у Markdown-документ з оцінкою достовірності.
-
 ## Гарантії поведінки
 
 - Кешує результати в межах одного прогону.

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

@@ -3,27 +3,12 @@ type: JS Module
 title: docgen-judge-measure.mjs
 resource: npm/rules/doc-files/js/docgen-judge-measure.mjs
 docgen:
-  crc: 86b3120f
+  crc: 4362c310
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 50
+  issues: no-overview,short-behavior,anchor-miss:report.json,best-of-2:retry-lost
 ---
 
-Файл аналізує надані файли коду, створюючи документацію та оцінюючи її якість відповідно до конфігурації, що міститься у report.json. Процес збирає результати для кожного файлу, використовуючи кешування у межах прогону на основі вмісту джерела та вже згенерованої документації. У кінці процес агрегує дані та зберігає повний звіт у report.json, а також виводить його у консоль.
-
-## Поведінка
-
-1. Зчитує список файлів для аналізу з аргументів командного рядка.
-2. Для кожного файлу зчитує його вміст.
-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,31 +3,12 @@ type: JS Module
 title: docgen-judge.mjs
 resource: npm/rules/doc-files/js/docgen-judge.mjs
 docgen:
-  crc: fcbf72fa
+  crc: d20a0bc7
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-Модуль реалізує механізм оцінки якості документації. Він визначає модель для оцінки за допомогою `JUDGE_MODEL`, перевіряє статус активності гейту через `JUDGE_ENABLED` та встановлює поріг впевненості за допомогою `JUDGE_CONFIDENCE`. Модуль отримує, парсить та визначає фінальний статус документації, викликаючи `judgeDoc` для отримання висновків, а також може використовувати `judgeFailsDoc` для визначення провалу.
-
-## Поведінка
-
-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 — Визначає, чи повинен документ бути позначений як погіршений, якщо вердикт є `inaccurate` і впевненість достатня.
-
 ## Гарантії поведінки
 
 - Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/js/docs/skill_meta.md

@@ -3,31 +3,38 @@ type: JS Module
 title: skill_meta.mjs
 resource: npm/rules/npm-module/js/skill_meta.mjs
 docgen:
-  crc: d02dd00d
+  crc: a134317c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Перевіряє структуру та конфігурацію скілів у каталозі `npm/skills`, використовуючи правила, визначені в `meta.json`. Валідує, що кожен скіл не містить файлу `auto.md`. Перевіряє валідність полів `worktree`, `auto` та `requireRoot` у `main.json` кожного скіла.
+## Огляд
+
+Скрипт проводить валідацію конфігурацій усіх каталогів у `npm/skills`, перевіряючи відповідність кожного скіла встановленому контракту. Аналіз здійснюється з урахуванням конфігурацій `meta.json` та `main.json`, що контролюють надійність полів, таких як `worktree`, `auto` та `requireRoot`. У разі успіху повідомляється про відповідність конфігурацій скілів визначеним правилам; у випадку виявлення помилок інформується про них.
 
 ## Поведінка
 
-1. Перевіряє наявність каталогу `npm/skills` у поточному робочому каталозі. Якщо каталог відсутній, операція завершується успішно.
-2. Ітерує по всіх підкаталогах у `npm/skills`.
-3. Для кожного підкаталогу виконується перевірка метаданих скіла:
-   а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
-   б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
-   в. Виконується перевірка полів `main.json` скіла:
-   i. `worktree` має бути булевим значенням.
-   ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
-   iii. `requireRoot` має бути булевим значенням, якщо визначений.
-   iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
-   г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
-4. Після перевірки всіх скілів повертається код виходу, що відображає загальний статус (0 — успіх, 1 — порушення).
+Поведінка
+
+1. Викликає check для перевірки всіх каталогів у `npm/skills`.
+2. Якщо каталог `npm/skills` відсутній, повідомляє про це як успішний результат, оскільки скілів для валідації немає.
+3. Для кожного каталогу скіла виконує валідацію.
+4. Перевіряє, чи існує файл `auto.md` у каталозі скіла; якщо так, повідомляє про його залишковий статус, оскільки метадані тепер знаходяться у `main.json`.
+5. Зчитує вміст `main.json` скіла. Якщо файл відсутній або невалідний, повідомляє про це і припиняє перевірку для цього скіла.
+6. Якщо `main.json` знайдено, викликає внутрішню перевірку полів для валідації його структури.
+7. Перевіряє, чи `worktree` є булевим значенням. Якщо ні, повідомляє про помилку.
+8. Перевіряє поле `auto`; якщо воно визначене, викликає внутрішній аналіз для визначення, чи є його значення коректним ("завжди" або непорожній масив правил). Якщо ні, повідомляє про нерозпізнаність.
+9. Перевіряє поле `requireRoot`; якщо воно визначене, перевіряє, чи є воно булевим значенням. Якщо ні, повідомляє про помилку.
+10. Перевіряє на суперечливість: якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, повідомляє про конфігураційну помилку, оскільки `worktree` вже вимагає кореня.
+11. Перевіряє поле `tier`; якщо воно визначене, перевіряє, чи є воно рядком і чи належить до визначених категорій скілів. Якщо ні, повідомляє про допустимі значення.
+12. Якщо всі поля `main.json` валідні, повідомляє про успішну валідацію скіла.
+13. Повертає загальний код завершення, що відображає всі зафіксовані порушення в каталогах скілів.
 
 ## Публічний API
 
-check — перевіряє відповідність усіх файлів `meta.json` у каталозі `npm/skills/<id>/` заданим критеріям.
+check — перевіряє відповідність структури всіх файлів конфігурації `npm/skills/<id>/meta.json` вимогам.
 
 ## Гарантії поведінки
 

package/rules/npm-module/js/skill_meta.mjs

@@ -3,7 +3,7 @@ import { existsSync, readdirSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
-import { parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
+import { SKILL_TIERS, parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
 
 /**
  * Перевіряє поля сирого meta.json одного скіла (без auto.md / відсутності файлу).
@@ -32,6 +32,10 @@ function checkSkillFields(id, raw, reporter) {
     )
     ok = false
   }
+  if (raw.tier !== undefined && !(typeof raw.tier === 'string' && SKILL_TIERS.includes(raw.tier))) {
+    reporter.fail(`skills/${id}: main.json.tier має бути ${SKILL_TIERS.map(t => `"${t}"`).join(' | ')}`)
+    ok = false
+  }
   return ok
 }
 

package/rules/python/docs/main.md

@@ -3,28 +3,28 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/python/main.mjs
 docgen:
-  crc: b072766d
+  crc: 2bdec93d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 95
 ---
 
 ## Огляд
 
-Виконує послідовність кроків для валідації коду Python відповідно до правил, визначених у (python.mdc). Перед запуском інструментів перевіряє наявність `pyproject.toml` у корені; якщо він відсутній, завершує роботу з кодом 0. Якщо файл присутній, перевіряє наявність `uv` у PATH, оскільки він є єдиним пакет-менеджером. Обов'язково виконує `uv lock --check` для підтвердження актуальності lock-файлу та `uv sync --frozen` для синхронізації середовища з `uv.lock` (див. https://docs.astral.sh/uv/). Опційні лінтери запускаються лише за умови їх доступності через `uv run`. При використанні `ruff` застосовується автоматичне виправлення (`auto-fix`), що модифікує робоче дерево. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), запобігаючи викиданню винятків назовні.
+Цей модуль виконує послідовність кроків для забезпечення якості коду Python, використовуючи інструменти з екосистеми [uv](https://docs.astral.sh/uv/). Якщо файл `pyproject.toml` відсутній у корені, процес завершується з кодом 0 без запуску інструментів. Якщо файл присутній, але `uv` не знайдено в PATH, це розглядається як помилка. Модуль гарантує актуальність lock-файлу (`uv lock --check`) та збірку середовища (`uv sync --frozen`) перед запуском лінтерів. Опціональні лінтери запускаються лише за умови їх доступності через `uv run`.
 
 ## Поведінка
 
-run виконує стандартну перевірку на основі контексту.
-runLintPythonSteps виконує повний цикл лінтування Python, включаючи перевірку `uv lock --check`, `uv sync --frozen` та запуск лінтерів, якщо `pyproject.toml` присутній.
-runLintPython запускає кроки лінтування Python, використовуючи механізм серіалізації через `runStandardLint`.
-lint оркеструє запуск `runLintPython` з опцією `readOnly` для детектних перевірок.
+run виконує стандартну перевірку проєкту, використовуючи контекст прогону.
+runLintPythonSteps виконує повний набір кроків лінтування Python, включаючи перевірку `pyproject.toml`, виконання `uv lock --check` та `uv sync --frozen`, а також запуск опціональних лінтерів (`ruff`, `mypy`) та перевірку ліцензій.
+runLintPython запускає повний процес лінтування Python, серіалізуючи його через стандартний механізм перевірки.
+lint оркеструє запуск `runLintPython`, надаючи можливість вказати режим без мутацій (`readOnly`).
 
 ## Публічний API
 
-run — Точка входу для виконання правил, яка перевіряє аспекти застосування (JS-занепокложення $\rightarrow$ політика $\rightarrow$ mdc-посилання).
-runLintPythonSteps — Виконує внутрішні етапи перевірки коду Python без збереження результатів.
-runLintPython — Публічний інтерфейс командного рядка для запуску перевірки коду Python, що забезпечує унікальність завдяки блоку блокування та аналізу стану Git-дерева.
-lint — Адаптер, що керує запуском перевірки коду Python, делегуючи це `runLintPython`.
+run — Основна точка входу правила, яка виконує перевірку (JS-занепокложення $\rightarrow$ політика $\rightarrow$ mdc-посилання) та викликає перевірку якості коду.
+runLintPythonSteps — Виконує внутрішні етапи перевірки якості Python-коду без збереження логів.
+runLintPython — Публічний інтерфейс для запуску перевірки якості Python-коду, який синхронізується з станом Git-дерева.
+lint — Координатор, що ініціює запуск перевірки якості Python-коду, делегуючи цю роботу `runLintPython`.
 
 ## Гарантії поведінки