@nitra/cursor 12.15.1 → 12.16.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/text/js/cspell-fix.mjs

@@ -20,7 +20,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { callLlm, preflightLocalModel } from '../../../lib/llm.mjs'
+import { runOneShot } from '../../../lib/pi-one-shot.mjs'
 
 /** Слово у рядку cspell: `<file>:<line>:<col> - Unknown word (xxx)`. */
 const UNKNOWN_WORD_RE = /Unknown word \(([^)]+)\)/u
@@ -114,10 +114,10 @@ export function appendWordsToDict(cwd, words) {
  * cspell-крок lint-text: класифікація → словник (нова схема).
  * @param {string} [cwd] корінь
  * @param {boolean} [readOnly] true → лише детект (нуль мутацій)
- * @param {boolean} [llmFix] opt-in omlx-класифікація (з `meta.json: llmFix:true`); без нього — лише детект
- * @returns {number} 0 — чисто; 1 — лишились знахідки / помилка середовища
+ * @param {boolean} [llmFix] opt-in LLM-класифікація (з `meta.json: llmFix:true`); без нього — лише детект
+ * @returns {Promise<number>} 0 — чисто; 1 — лишились знахідки / помилка середовища
  */
-export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = false) {
+export async function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = false) {
   const bin = resolveCmd('npx')
   if (!bin) {
     process.stderr.write('❌ npx не знайдено в PATH (cspell).\n')
@@ -133,9 +133,8 @@ export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = fa
 
   // Fix-режим: класифікація знахідок (bounded JSON-вихід), валідні → у словник.
   const model = fixModel()
-  const problem = preflightLocalModel(model)
-  if (problem) {
-    process.stdout.write(`⚠️  cspell: класифікацію пропущено (${problem})\n`)
+  if (!model) {
+    process.stdout.write('⚠️  cspell: класифікацію пропущено (локальну модель не задано)\n')
     process.stdout.write(first.out)
     return first.code
   }
@@ -148,19 +147,19 @@ export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = fa
     )
   }
 
-  let text
-  try {
-    text = callLlm([{ role: 'user', content: classifyPrompt(batch) }], model, {
-      caller: 'cspell-classify',
-      maxTokens: 4000
-    })
-  } catch (error) {
-    process.stdout.write(`⚠️  cspell: omlx-класифікація впала (${error.message}) — без авто-словника\n`)
+  const res = await runOneShot({
+    messages: [{ role: 'user', content: classifyPrompt(batch) }],
+    modelSpec: model,
+    caller: 'cspell-classify',
+    cwd
+  })
+  if (res.error) {
+    process.stdout.write(`⚠️  cspell: LLM-класифікація впала (${res.error}) — без авто-словника\n`)
     process.stdout.write(first.out)
     return first.code
   }
 
-  const parsed = parseClassify(text)
+  const parsed = parseClassify(res.content)
   if (!parsed) {
     process.stdout.write('⚠️  cspell: не вдалося розпарсити класифікацію — без авто-словника\n')
     process.stdout.write(first.out)

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

@@ -3,24 +3,31 @@ type: JS Module
 title: cspell-fix.mjs
 resource: npm/rules/text/js/cspell-fix.mjs
 docgen:
-  crc: e00c233e
+  crc: 3469ac34
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  score: 95
 ---
 
-Модуль інтегрує cspell у ланцюжку lint-text для класифікації невідомих слів згідно зі схемою docs/specs/2026-06-15-opportunistic-llm-fix-tier.md. Він виявляє невідомі слова, класифікує їх за допомогою LLM у межах omlx-класифікації. Валідні слова автоматично дописуються до `.cspell.json#words` (відповідно до конфігурацій .cspell.json та meta.json). Невалідні знахідки залишаються для ручного рев'ю. Процес є read-only (нуль мутацій), оскільки fix-режим не переписує файли, а лише класифікує знахідки. Після дописування словника виконується re-detect. Гейт-механізм гарантує, що cspell поверне ненульовий код, якщо нерозкласифіковані або потенційні одруки залишилися.
+## Огляд
+
+Огляд: Цей модуль інтегрує `cspell` у ланцюжок `lint-text` для забезпечення термінологічної коректності у тексті, використовуючи схему `omlx-класифікації`. Він ідентифікує неозначені слова, класифікує їх за допомогою LLM та автоматично доповнює словник `.cspell.json` валідними термінами, залишаючи потенційні помилки для ручного рев'ю.
+
+Поведінка:
+unknownWords витягує унікальні неозначені слова з виводу інструмента `cspell`.
+appendWordsToDict додає визначені як валідні слова до конфігураційного файлу `.cspell.json`, оновлюючи його в алфавітному порядку.
+runCspellText запускає процес класифікації неозначених слів, спочатку визначаючи їх, а потім, за умови увімкненого LLM-класифікатора, відправляючи їх на перевірку та додаючи валідні слова до словника, після чого повторно перевіряє код.
 
 ## Поведінка
 
-unknownWords витягує унікальні «Unknown word» з виводу cspell.
-appendWordsToDict дописує класифіковані валідні слова у `.cspell.json#words`, сортуючи та усуваючи дублікати.
-runCspellText запускає cspell, класифікує знахідки за допомогою LLM (якщо `llmFix` встановлено), дописує валідні слова у словник та повторно запускає cspell для перевірки, повертаючи код виходу.
+unknownWords витягує унікальні неозначені слова з виводу інструмента `cspell`.
+appendWordsToDict додає визначені як валідні слова до конфігураційного файлу `.cspell.json`, оновлюючи його в алфавітному порядку.
+runCspellText запускає процес класифікації неозначених слів, спочатку визначаючи їх, а потім, за умови увімкненого LLM-класифікатора, відправляючи їх на перевірку та додаючи валідні слова до словника, після чого повторно перевіряє код.
 
 ## Публічний API
 
-unknownWords — Збирає унікальні слова, які не були знайдені у cspell.
-appendWordsToDict — Додає зібрані слова до словника `.cspell.json` у відсортованому та унікальному вигляді.
-runCspellText — Виконує перевірку тексту за допомогою cspell для формування словника за новою схемою.
+unknownWords — Збирає унікальні слова, які `cspell` виявив як незнайомі у виводі.
+appendWordsToDict — Додає зібрані слова до словника `.cspell.json#words`, забезпечуючи унікальність та сортування.
+runCspellText — Виконує лінтування тексту з `cspell`: класифікує слова та оновлює словник з новою схемою.
 
 ## Гарантії поведінки