@nitra/cursor 12.15.1 → 12.16.1

package/rules/text/main.mjs

@@ -110,9 +110,9 @@ function preflight(dep) {
  * Внутрішні кроки `lint-text` без локу.
  * @param {boolean} [readOnly] true → лише детект без авто-фіксу (нуль мутацій — CI/pre-commit)
  * @param {boolean} [llmFix] opt-in omlx-класифікація cspell (інші кроки фіксяться детерміновано за readOnly)
- * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
+ * @returns {Promise<number>} 0 — все OK, інакше — код першого кроку, що впав
  */
-function runLintTextSteps(readOnly = false, llmFix = false) {
+async function runLintTextSteps(readOnly = false, llmFix = false) {
   // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
   ensureTool('shellcheck')
   ensureTool('dotenv-linter')
@@ -120,8 +120,8 @@ function runLintTextSteps(readOnly = false, llmFix = false) {
   // patch потрібен лише для авто-фіксу shellcheck; у read-only пропускаємо preflight.
   if (!readOnly && !preflight(PATCH_PREFLIGHT)) return 1
 
-  console.log(`\n▶ cspell (${!readOnly && llmFix ? 'omlx-класифікація + словник + перевірка' : 'перевірка'})`)
-  const cspellCode = runCspellText(process.cwd(), readOnly, llmFix)
+  console.log(`\n▶ cspell (${!readOnly && llmFix ? 'LLM-класифікація + словник + перевірка' : 'перевірка'})`)
+  const cspellCode = await runCspellText(process.cwd(), readOnly, llmFix)
   if (cspellCode !== 0) return cspellCode
 
   console.log(`\n▶ shellcheck (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} *.sh)`)

package/schemas/skill-meta.json

@@ -17,6 +17,14 @@
     "worktree": {
       "type": "boolean",
       "description": "true — виконувати скіл в окремому git-worktree, один інстанс за раз (без паралельного запуску); false — у worktree не виконується."
+    },
+    "requireRoot": {
+      "type": "boolean",
+      "description": "true — скіл мутує CWD без worktree-ізоляції і має стартувати з кореня репо. Для worktree:true поле зайве (корінь гарантує worktree)."
+    },
+    "tier": {
+      "description": "Абстрактна тира моделі (capability, НЕ провайдер) для агентного виконання скіла через pi-runner: кожна каскадить local→cloud (напр. avg → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG), тож avg ≠ \"локальна\". За відсутності — \"max\" (відкриті скіли потребують сильної моделі).",
+      "enum": ["min", "avg", "max"]
     }
   }
 }

package/scripts/docs/skills-cli.md

@@ -3,40 +3,36 @@ type: JS Module
 title: skills-cli.mjs
 resource: npm/scripts/skills-cli.mjs
 docgen:
-  crc: 85da573a
+  crc: e2d5fac6
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Файл надає інструменти для запуску скілів пакета `@nitra/cursor` без синку правил у проєкт. Він зчитує інструкції скілів з файлів `SKILL.md` та збирає контекст з `package.json`, `tsconfig.json` та `.n-cursor.json` для формування промпту. Зібраний промпт делегується в `cursor-agent` або `claude` для виконання необхідних дій.
+## Огляд
 
-## Поведінка
-
-normalizeSkillId
-Перетворює ім'я скілу на ідентифікатор, видаляючи префікс n-
-
-listSkillIds
-Отримує відсортований список ідентифікаторів скілів, що мають файл SKILL.md
+Цей модуль забезпечує керування функціоналом скілів пакета `@nitra/cursor`. Він каталогізує доступні скіли на основі наявності файлу `SKILL.md` у відповідному пакеті. Для виконання скілу збирається контекст, що включає інструкції скілу та інформацію з конфігураційних файлів проєкту: `package.json`, `tsconfig.json`, `.n-cursor.json` та `main.json`. Система дозволяє або вивести список доступних скілів (`npx @nitra/cursor skill list`), або ініціювати виконання обраного скілу (наприклад, `npx @nitra/cursor skill pi taze`), з можливістю передачі додаткових аргументів. Пріоритетним механізмом виконання є інтеграція з вбудованим pi-агентом, тоді як для забезпечення сумісності підтримуються застарілі виклики через зовнішні CLI (`cursor`, `claude`).
 
-buildSkillPrompt
-Створює промпт, збираючи інструкцію скілу та контекст поточного проєкту з файлів package.json, tsconfig.json та .n-cursor.json
-
-resolveBundledPackageRoot
-Визначає абсолютний шлях до кореня пакета з урахуванням модуля
+## Поведінка
 
-runSkillsCli
-Запускає CLI для виконання скілів, збираючи промпт та контекст проєкту, та делегує виконання в `cursor-agent` або `claude`
+Поведінка
+normalizeSkillId знімає префікс `n-` з імені скілу для приведення його до стандартного ID.
+listSkillIds отримує відсортований список ID скілів, які мають файл `SKILL.md` у вказаній директорії скілів.
+buildSkillPrompt збирає комплексний промпт для виконання скілу, об'єднуючи інструкцію скілу з конфігураційними файлами проєкту, такими як `package.json`, `tsconfig.json` та `.n-cursor.json`.
+resolveBundledPackageRoot визначає абсолютний шлях до кореня пакету `@nitra/cursor`, використовуючи інформацію про поточний модуль.
+runSkillsCli виконує логіку командного інтерфейсу для керування скілами: може вивести список доступних скілів, зібрати промпт для скілу або ініціювати його виконання через вбудований pi-агент, використовуючи зовнішні CLI як резервний варіант.
 
 ## Публічний API
 
-normalizeSkillId — перетворює ідентифікатор навички.
-listSkillIds — отримує список ідентифікаторів навичок.
-buildSkillPrompt — створює запит для навички.
-resolveBundledPackageRoot — визначає основний каталог пакета.
-runSkillsCli — запускає клієнт для навичок.
+- normalizeSkillId — знімає префікс `n-` з імені скілу, приводячи його до id каталогу в пакеті.
+- listSkillIds — повертає відсортований список id скілів, що мають `SKILL.md`.
+- buildSkillPrompt — збирає промпт виконання: інструкція скілу + контекст проєкту (`package.json`, `tsconfig.json`, `.n-cursor.json`); кидає, якщо скіл невідомий.
+- resolveBundledPackageRoot — абсолютний шлях до кореня встановленого пакета `@nitra/cursor`.
+- runSkillsCli — асинхронний entrypoint підкоманди `skill`: `list`, друк промпта на stdout, або виконання через `pi` (рекомендовано), `cursor`/`claude` (deprecated). Повертає exit-код.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- Сам модуль лише читає файли й збирає промпт; **виконання** делегується агенту: `pi` (вбудований, мутує дерево, запускає bash) або зовнішнім `cursor`/`claude` CLI.
+- Тира моделі для `pi`-runner береться з `main.json.tier` скіла (дефолт `max`).
+- `cursor`/`claude` — deprecated: друкують попередження й лишаються як fallback, доки не налаштовано pi-модель.

package/scripts/lib/adr/docs/normalize-cli.md

@@ -3,29 +3,12 @@ type: JS Module
 title: normalize-cli.mjs
 resource: npm/scripts/lib/adr/normalize-cli.mjs
 docgen:
-  crc: 63a18347
+  crc: 222bfca4
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-Цей файл є CLI-обгорткою для локального нормалізатора ADR. Він зчитує шляхи до чернеток (`--batch <file>`) та список чистих ADR (`--clean <file>`), використовуючи директорію ADR (`--adr-dir <dir>`) для резолву шляхів. Обгортка запускає `normalizePipeline`, яка генерує JSON-контракт у форматі `{ "operations": [...] }` та виводить його у stdout для подальшого парсингу bash-скриптом. Прогрес та помилки записуються у stderr. Поведінка нормалізатора може бути змінена через змінні середовища: `ADR_NORMALIZE_ALLOW_CLOUD` контролює можливість хмарної ескалації, а `ADR_NORMALIZE_VOTES` визначає кількість голосів self-consistency для чистих ADR.
-
-## Поведінка
-
-1. Викликати runAdrNormalizeLocalCli.
-2. Зчитувати список шляхів до чернеток батчу з файлу, вказаного через аргумент `--batch`.
-3. Зчитувати список імен чистих ADR (кандидатів до злиття) з файлу, вказаного через аргумент `--clean`, якщо він наданий.
-4. Визначати директорію ADR, використовуючи аргумент `--adr-dir` або за замовчуванням `cwd/docs/adr`.
-5. Зчитувати вміст кожної чернетки батчу, резолвя шляхи відносно `--adr-dir`.
-6. Зчитувати значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES`.
-7. Викликати внутрішній механізм нормалізації, передаючи зібрані чернетки, список чистих ADR, та конфігурацію, отриману з змінних середовища.
-8. Виводити інформацію про прогрес та статистику в stderr.
-9. Виводити JSON-об'єкт, що містить операції, у stdout.
-
-## Публічний API
-
-runAdrNormalizeLocalCli — запускає субкоманду, виводячи JSON операцій у стандартний вивід та прогрес у стандартний помилковий вивід.
-
 ## Гарантії поведінки
 
 - Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -3,42 +3,12 @@ type: JS Module
 title: normalize-pipeline.mjs
 resource: npm/scripts/lib/adr/normalize-pipeline.mjs
 docgen:
-  crc: 9f2d42d3
+  crc: 8e9ca76f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток архітектурних рішень (ADR). Він працює за принципом інверсії керування: JavaScript оркеструє процес, а LLM відповідає лише на вузькі, верифіковані запитання, будучи заточеним під малу локальну модель (omlx/gemma-4b). LLM використовується лише для бінарного судження схожості між записами (наприклад, через `edge-judge`) та витягування змісту секцій у JSON (через `gen-MADR`). Конвеєр збирає, валідує та складає повний MADR-каркас, використовуючи кластеризацію (`cluster` та `union-find`) та проходить через `validation gate`, повертаючи результат у вигляді операцій для застосування.
-
-## Поведінка
-
-tokenize: Токенізує назву або слаг, видаляючи стоп-слова та розширюючи його на значущі токени.
-jaccard: Обчислює коефіцієнт Jaccard між двома множинами токенів.
-draftTitle: Витягує заголовок з тіла чернетки, використовуючи ADR-шаблон або перший не-MADR заголовок.
-isNoDecision: Детерміновано визначає, чи рішення в чернетці явно не прийняте.
-buildEdges: Будує кандидати-ребра між чернетками та між чернетками і чистими ADR-файлами на основі лексичної схожості.
-validateMadr: Перевіряє згенерований MADR-текст на відповідність вимогам OKF та структурним елементам.
-madrDate: Детерміновано визначає ISO-дату для поля **Date:**, використовуючи дані з чернетки або імені файлу.
-normalizeSections: Нормалізує сирий JSON-вивід LLM у строгу структуру секцій MADR, толерантно до дрібних відхилень моделі.
-assembleMadr: Збирає канонічний MADR-markdown, використовуючи заголовок, дату та нормалізований контент секцій.
-genMadr: Витягує зміст архітектурного рішення з чернетки у JSON, а потім збирає його у валідний MADR-текст.
-normalizePipeline: Виконує повний конвеєр нормалізації, кластеризуючи чернетки та генеруючи операції для застосування.
-
-## Публічний API
-
-tokenize — Розбиває назву чи слаг на значущі слова, ігноруючи стоп-слова.
-jaccard — Вимірює схожість двох наборів слів.
-draftTitle — Витягує заголовок з чернетки, надаючи пріоритет заголовку ADR.
-isNoDecision — Визначає, чи не було прийнято рішення у чернетці, щоб уникнути створення зайвих ADR.
-buildEdges — Створює потенційні зв'язки між елементами на основі схожості слів.
-validateMadr — Перевіряє якість згенерованого документа ADR.
-madrDate — Формує стандартизовану дату для документа, використовуючи метадані або ім'я файлу.
-normalizeSections — Приводить неструктурований вивід генеративної моделі до чіткого формату секцій.
-assembleMadr — Збирає повний, стандартизований документ ADR, використовуючи фіксовані шаблони.
-genMadr — Створює чернетку документа ADR на основі вхідних даних.
-normalizePipeline — Виконує повний потік обробки даних, повертаючи результати та статистику.
-
 ## Гарантії поведінки
 
 - (специфічних машинно-виведених гарантій немає)

package/scripts/lib/adr/normalize-cli.mjs

@@ -43,7 +43,7 @@ const readLines = (file) =>
  * @param {string[]} argv аргументи після назви команди
  * @returns {number} exit-code (0 — успіх, 1 — помилка вводу)
  */
-export function runAdrNormalizeLocalCli(argv) {
+export async function runAdrNormalizeLocalCli(argv) {
   const args = parseArgs(argv)
   const adrDir = args['adr-dir'] ?? join(process.cwd(), 'docs/adr')
   if (!args.batch) {
@@ -61,7 +61,7 @@ export function runAdrNormalizeLocalCli(argv) {
   const allowCloud = env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
   const votes = Number(env.ADR_NORMALIZE_VOTES) || 2
 
-  const { operations, stats, trace } = normalizePipeline(drafts, cleanList, {
+  const { operations, stats, trace } = await normalizePipeline(drafts, cleanList, {
     allowCloud,
     votes,
     onProgress: (m) => console.error(`adr-normalize-local: ${m}`)

package/scripts/lib/adr/normalize-pipeline.mjs

@@ -24,8 +24,8 @@
  * Повертає той самий operations[]-контракт, що й single-shot — apply-логіка спільна.
  */
 import { z } from 'zod'
-import { callLlm, classifyOmlxError } from '../../../lib/llm.mjs'
-import { CLOUD_MIN, resolveModel } from '../../../lib/models.mjs'
+import { runOneShot } from '../../../lib/pi-one-shot.mjs'
+import { CLOUD_MIN, resolveModel } from '../../../lib/pi-model-tiers.mjs'
 
 // ─────────────────────────── Stage 0: retrieval (JS) ───────────────────────────
 
@@ -168,36 +168,44 @@ const LOCAL = () => resolveModel('min')
  * @param {Array<{role:string,content:string}>} messages чат-повідомлення для LLM
  * @param {(raw:string)=>any} parse валідатор (кидає на невалідному)
  * @param {{label:string, allowCloud:boolean, attempts?:number, stats:object, maxTokens?:number}} cfg конфіг каскаду (мітка, дозвіл на хмару, спроби, лічильники, ліміт токенів)
- * @returns {any} результат parse
+ * @returns {Promise<any>} результат parse
  * @throws {Error} якщо всі спроби провалені
  */
-function callWithCascade(messages, parse, cfg) {
+async function callWithCascade(messages, parse, cfg) {
   const attempts = cfg.attempts ?? 2
-  const temps = [0.1, 0.4, 0.7]
   let lastErr = null
   for (let a = 0; a < attempts; a++) {
-    try {
-      cfg.stats.localCalls++
-      const raw = callLlm(messages, LOCAL(), {
-        timeoutMs: 120_000,
-        temperature: temps[a] ?? 0.2,
-        maxTokens: cfg.maxTokens ?? 4096,
-        caller: `adr-pipe:${cfg.label}`
-      })
-      return parse(raw)
-    } catch (error) {
-      lastErr = error
-      if (classifyOmlxError(error.message) === 'infra') break
+    cfg.stats.localCalls++
+    const res = await runOneShot({ messages, modelSpec: LOCAL(), timeoutMs: 120_000, caller: `adr-pipe:${cfg.label}` })
+    if (!res.error) {
+      try {
+        return parse(res.content)
+      } catch (error) {
+        lastErr = error // невалідний вихід → наступна спроба
+        continue
+      }
     }
+    lastErr = new Error(res.error)
+    // infra (registry/session/модель недоступна) → ретрай локально марний.
+    if (/registry:|session:|не знайдена/i.test(res.error)) break
   }
   if (cfg.allowCloud && CLOUD_MIN) {
-    try {
-      cfg.stats.cloudCalls++
-      cfg.stats.escalations++
-      const raw = callLlm(messages, CLOUD_MIN, { timeoutMs: 120_000, temperature: 0.2, maxTokens: cfg.maxTokens ?? 4096, caller: `adr-pipe:${cfg.label}:cloud` })
-      return parse(raw)
-    } catch (error) {
-      lastErr = error
+    cfg.stats.cloudCalls++
+    cfg.stats.escalations++
+    const res = await runOneShot({
+      messages,
+      modelSpec: CLOUD_MIN,
+      timeoutMs: 120_000,
+      caller: `adr-pipe:${cfg.label}:cloud`
+    })
+    if (!res.error) {
+      try {
+        return parse(res.content)
+      } catch (error) {
+        lastErr = error
+      }
+    } else {
+      lastErr = new Error(res.error)
     }
   }
   cfg.stats.failures++
@@ -244,20 +252,27 @@ same=true ЛИШЕ якщо це по суті одне рішення (дубл
  * @param {{votes?:number, minConf?:number}} [vote] override голосів і порога на тип ребра
  * @returns {{same:boolean, votes:object[]}} підтвердження same та сирі голоси
  */
-function judgeEdge(aTitle, aBody, bTitle, bBody, cfg, vote = {}) {
+async function judgeEdge(aTitle, aBody, bTitle, bBody, cfg, vote = {}) {
   const nVotes = vote.votes ?? cfg.votes ?? 2
   const minConf = vote.minConf ?? 0.5
   const user = `Запис A — "${aTitle}":\n${aBody.slice(0, 1500)}\n\n---\n\nЗапис B — "${bTitle}":\n${bBody.slice(0, 1500)}\n\nЦе одне й те саме рішення?`
-  const parse = (raw) => EdgeSchema.parse(extractJson(raw))
+  const parse = raw => EdgeSchema.parse(extractJson(raw))
   const votes = []
   for (let v = 0; v < nVotes; v++) {
     try {
-      votes.push(callWithCascade([{ role: 'system', content: EDGE_SYS }, { role: 'user', content: user }], parse, { label: 'edge', allowCloud: cfg.allowCloud, stats: cfg.stats, maxTokens: 300 }))
+      votes.push(
+        await callWithCascade([{ role: 'system', content: EDGE_SYS }, { role: 'user', content: user }], parse, {
+          label: 'edge',
+          allowCloud: cfg.allowCloud,
+          stats: cfg.stats,
+          maxTokens: 300
+        })
+      )
     } catch {
       votes.push({ same: false, confidence: 0, reason: 'judge failed → conservative different' })
     }
   }
-  const sameCount = votes.filter((v) => v.same && v.confidence >= minConf).length
+  const sameCount = votes.filter(v => v.same && v.confidence >= minConf).length
   return { same: sameCount === votes.length, votes }
 }
 
@@ -275,11 +290,16 @@ const KIND_SYS = `Ти оцінюєш чернетку архітектурно
 Поверни ЛИШЕ JSON: { "kind": "standalone"|"trivial", "reason": "<коротко українською>" }
 Якщо сумніваєшся — "standalone" (краще зберегти).`
 
-function judgeKind(title, body, cfg) {
+async function judgeKind(title, body, cfg) {
   const user = `Чернетка — "${title}":\n${body.slice(0, 2500)}\n\nstandalone чи trivial?`
-  const parse = (raw) => KindSchema.parse(extractJson(raw))
+  const parse = raw => KindSchema.parse(extractJson(raw))
   try {
-    return callWithCascade([{ role: 'system', content: KIND_SYS }, { role: 'user', content: user }], parse, { label: 'kind', allowCloud: cfg.allowCloud, stats: cfg.stats, maxTokens: 200 })
+    return await callWithCascade([{ role: 'system', content: KIND_SYS }, { role: 'user', content: user }], parse, {
+      label: 'kind',
+      allowCloud: cfg.allowCloud,
+      stats: cfg.stats,
+      maxTokens: 200
+    })
   } catch {
     return { kind: 'standalone', reason: 'judge failed → conservative standalone' }
   }
@@ -424,20 +444,28 @@ export function assembleMadr({ title, date, sections: s }) {
   ].join('\n')
 }
 
-export function genMadr(title, body, captured, cfg, file = '') {
+export async function genMadr(title, body, captured, cfg, file = '') {
   const date = madrDate(captured, file)
   const slug = slugify(title)
   const user = `Чернетка "${title}":\n\n${body.slice(0, 4000)}\n\nВитягни зміст рішення у JSON.`
-  const parse = (raw) => {
+  const parse = raw => {
     const sections = normalizeSections(extractJson(raw))
-    if (!sections.context && !sections.chosen && !sections.rationale) throw new Error('empty extraction (no context/decision)')
+    if (!sections.context && !sections.chosen && !sections.rationale) {
+      throw new Error('empty extraction (no context/decision)')
+    }
     const content = assembleMadr({ title, date, sections })
     const v = validateMadr(content)
     if (!v.ok) throw new Error(`MADR invalid: ${v.errors.join('; ')}`)
     return content
   }
   try {
-    const content = callWithCascade([{ role: 'system', content: GEN_SYS }, { role: 'user', content: user }], parse, { label: 'gen', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 3, maxTokens: 2048 })
+    const content = await callWithCascade([{ role: 'system', content: GEN_SYS }, { role: 'user', content: user }], parse, {
+      label: 'gen',
+      allowCloud: cfg.allowCloud,
+      stats: cfg.stats,
+      attempts: 3,
+      maxTokens: 2048
+    })
     return { content, slug, valid: true }
   } catch (error) {
     cfg.stats.madrInvalid++
@@ -451,7 +479,7 @@ export function genMadr(title, body, captured, cfg, file = '') {
 // новий зміст-прозу; заголовок із детермінованою датою додає genMerge.
 const MERGE_SYS = `Ти готуєш короткий додаток до існуючого ADR. Напиши ЛИШЕ новий зміст (проза/bullets), якого ще НЕМА в цільовому ADR — уточнення/виправлення/продовження. Стисло, українською, без заголовків, без code-fence, без передмови.`
 
-function genMerge(title, body, captured, targetTitle, cfg, file = '') {
+async function genMerge(title, body, captured, targetTitle, cfg, file = '') {
   const date = madrDate(captured, file)
   const user = `Цільовий ADR: "${targetTitle}".\nЧернетка-доповнення "${title}" (${date}):\n${body.slice(0, 2500)}\n\nЛише новий зміст, без заголовка.`
   const head = `## Update ${date}`
@@ -464,7 +492,13 @@ function genMerge(title, body, captured, targetTitle, cfg, file = '') {
     return `${head}\n\n${cleaned}`
   }
   try {
-    return callWithCascade([{ role: 'system', content: MERGE_SYS }, { role: 'user', content: user }], parse, { label: 'merge', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 2, maxTokens: 1500 })
+    return await callWithCascade([{ role: 'system', content: MERGE_SYS }, { role: 'user', content: user }], parse, {
+      label: 'merge',
+      allowCloud: cfg.allowCloud,
+      stats: cfg.stats,
+      attempts: 2,
+      maxTokens: 1500
+    })
   } catch {
     return `${head}\n\n(доповнення з чернетки "${title}")`
   }
@@ -498,7 +532,7 @@ const noop = () => {
  * @param {{allowCloud?:boolean, votes?:number, onProgress?:(m:string)=>void}} [opts] хмарна ескалація, кількість голосів і колбек прогресу
  * @returns {{operations:object[], stats:object, trace:object}} операції apply-ops, лічильники та діагностичний trace
  */
-export function normalizePipeline(drafts, cleanList, opts = {}) {
+export async function normalizePipeline(drafts, cleanList, opts = {}) {
   const allowCloud = opts.allowCloud ?? false
   const log = opts.onProgress ?? noop
   const stats = { localCalls: 0, cloudCalls: 0, escalations: 0, failures: 0, madrInvalid: 0 }
@@ -522,7 +556,7 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
   const dsu = makeDSU(drafts.length)
   const confirmedDD = []
   for (const [i, j] of dd) {
-    const r = judgeEdge(titles[i], drafts[i].body, titles[j], drafts[j].body, cfg, { votes: 3, minConf: 0.6 })
+    const r = await judgeEdge(titles[i], drafts[i].body, titles[j], drafts[j].body, cfg, { votes: 3, minConf: 0.6 })
     if (r.same) { dsu.union(i, j); confirmedDD.push([i, j]) }
   }
   log(`edge-judge: ${confirmedDD.length}/${dd.length} draft-draft ребер підтверджено`)
@@ -534,7 +568,7 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
   for (const [i, cands] of dcByDraft) {
     for (const c of cands) {
       const cTitle = stripAdrName(c)
-      const r = judgeEdge(titles[i], drafts[i].body, cTitle, cTitle, cfg)
+      const r = await judgeEdge(titles[i], drafts[i].body, cTitle, cTitle, cfg)
       if (r.same) { cleanTarget[i] = c; break }
     }
   }
@@ -578,7 +612,7 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
   // одинаки без clean-target → kind-judge
   for (let i = 0; i < drafts.length; i++) {
     if (decision[i].op === 'kind') {
-      const k = judgeKind(titles[i], drafts[i].body, cfg)
+      const k = await judgeKind(titles[i], drafts[i].body, cfg)
       decision[i] = k.kind === 'trivial' ? { op: 'delete', reason: k.reason } : { op: 'rewrite' }
     }
   }
@@ -587,7 +621,7 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
   const slugByIdx = Array.from({ length: drafts.length }).fill(null)
   for (let i = 0; i < drafts.length; i++) {
     if (decision[i].op !== 'rewrite') continue
-    const g = genMadr(titles[i], drafts[i].body, captured[i], cfg, drafts[i].file)
+    const g = await genMadr(titles[i], drafts[i].body, captured[i], cfg, drafts[i].file)
     slugByIdx[i] = g.slug
     if (g.valid) {
       operations.push({ op: 'rewrite', file: drafts[i].file, slug: g.slug, content: g.content })
@@ -603,11 +637,11 @@ export function normalizePipeline(drafts, cleanList, opts = {}) {
     if (d.op === 'merge-anchor') {
       const slug = slugByIdx[d.anchorIdx]
       if (!slug) { log(`merge-anchor ${drafts[i].file}: anchor gen failed → skip`); continue }
-      const add = genMerge(titles[i], drafts[i].body, captured[i], titles[d.anchorIdx], cfg, drafts[i].file)
+      const add = await genMerge(titles[i], drafts[i].body, captured[i], titles[d.anchorIdx], cfg, drafts[i].file)
       operations.push({ op: 'merge-into', file: drafts[i].file, target: `${slug}.md`, additions: add })
     } else if (d.op === 'merge-existing') {
       const cTitle = stripAdrName(d.target)
-      const add = genMerge(titles[i], drafts[i].body, captured[i], cTitle, cfg, drafts[i].file)
+      const add = await genMerge(titles[i], drafts[i].body, captured[i], cTitle, cfg, drafts[i].file)
       operations.push({ op: 'merge-into', file: drafts[i].file, target: d.target, additions: add })
     } else if (d.op === 'delete') {
       operations.push({ op: 'delete', file: drafts[i].file, reason: d.reason })

package/scripts/lib/docs/skill-meta.md

@@ -3,28 +3,45 @@ type: JS Module
 title: skill-meta.mjs
 resource: npm/scripts/lib/skill-meta.mjs
 docgen:
-  crc: 9ff67388
+  crc: fd8085f3
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Спільний парсер метаданих скіла, що зчитує дані з `main.json`. `main.json` є єдиним джерелом правди для скіла, визначаючи його умови автоактивації (`auto`, де `SKILL_ALWAYS` означає "завжди"), чи виконувати скіл в окремому git-worktree (`worktree`), та чи вимагає він запуску з кореня репозиторію (`requireRoot`). Модуль надає функції для читання сирих метаданих та визначення умов, використовуючи механізм fail-safe, який перехоплює помилки, не кидаючи винятків. Цим хелпером користуються `auto-skills.mjs`, `n-cursor.js` та `npm-module/js/skill_meta.mjs`.
+Спільний парсер метаданих скіла з `npm/skills/<id>/main.json`. Цей механізм зчитує та інтерпретує конфігурацію скіла, використовуючи `main.json` як єдине джерело правди. Він визначає умову автоактивації (`auto`, де `SKILL_ALWAYS` означає безумовну активацію), необхідність роботи з кореневою директорією (`requireRoot`), та визначає, чи повинен скіл виконуватися ізольовано в окремому git-worktree (`worktree`).
+
+Поведінка
+SKILL_ALWAYS — Константа-рядок, яка позначає, що скіл має бути активований завжди.
+SKILL_TIERS — Список допустимих рівнів моделі для виконання скіла.
+DEFAULT_SKILL_TIER — Константа-рядок, яка встановлює рівень моделі за замовчуванням, якщо він не вказаний у метаданих.
+parseSkillAutoSpec — Визначає умови, за яких скіл може бути автоматично активований, ґрунтуючись на конфігурації `main.json`.
+skillRequiresRoot — Визначає, чи вимагає скіл запуску з кореневої директорії репозиторію. Зверніть увагу, що скіли з `worktree:true` не вимагають цього поля явно, оскільки коренем є сам worktree.
+skillTier — Визначає рівень моделі, який буде використаний для виконання скіла, враховуючи конфігурацію `main.json` або повертаючи `DEFAULT_SKILL_TIER`.
+readSkillMetaRaw — Зчитує та парсить сирі метадані скіла з файлу `main.json`. При виявленні помилок парсингу або в IO-операціях, функція не генерує винятки, а повертає `null` (fail-safe).
 
 ## Поведінка
 
-SKILL_ALWAYS — надає літерал для безумовної автоактивації скіла.
-parseSkillAutoSpec — перетворює значення поля `auto` з `main.json` у специфікацію автоактивації скіла.
-skillRequiresRoot — визначає, чи вимагає скіл запуску з кореня репозиторію, на основі метаданих.
-readSkillMetaRaw — читає та парсить файл `main.json` з каталогу скіла, повертаючи його вміст або `null` у разі помилки.
+SKILL_ALWAYS — Константа, що позначає безумовну активацію скіла.
+SKILL_TIERS — Список допустимих рівнів моделі для виконання скіла.
+DEFAULT_SKILL_TIER — Тир моделі, який застосовується за замовчуванням, якщо рівень не вказаний у метаданих.
+parseSkillAutoSpec — Визначає, як скіл може бути автоматично активований на основі конфігурації `main.json`.
+skillRequiresRoot — Визначає, чи повинен скіл виконуватися з кореневої директорії репозиторію, базуючись на налаштуваннях `main.json`.
+skillTier — Визначає рівень моделі, який буде використано для виконання скіла, приймаючи в до уваги значення з `main.json` або повертаючи `DEFAULT_SKILL_TIER`.
+readSkillMetaRaw — Зчитує та парсить метадані скіла з файлу `main.json` за вказаним шляхом, обробляючи можливі помилки формату.
 
 ## Публічний API
 
-SKILL_ALWAYS — позначка для безумовної активації
-parseSkillAutoSpec — витягує налаштування автоматичного запуску зі `main.json`
-skillRequiresRoot — визначає, чи потрібен запуск скіла з кореня репозиторію
-readSkillMetaRaw — зчитує та аналізує метадані окремого скіла з `main.json`
+**SKILL_ALWAYS** — позначка, що робить скіл автоматично активним у будь-якій ситуації.
+**SKILL_TIERS** — список допустимих рівнів (тирів) моделей, які можуть виконувати скіл через `pi`-runner.
+**DEFAULT_SKILL_TIER** — рівень моделі, який використовується за замовчуванням для скілів, якщо `main.json` цього скіла не вказує конкретний рівень.
+**parseSkillAutoSpec** — визначає, чи має скіл автоматично запускатися на основі конфігурації в `main.json`.
+**skillRequiresRoot** — позначає, чи повинен скіл виконуватися з кореневої директорії репозиторію; це захист від несанкціонованого запуску.
+**skillTier** — визначає необхідний рівень моделі для виконання скіла, використовуючи значення з `main.json` або встановлюючи `DEFAULT_SKILL_TIER`.
+**readSkillMetaRaw** — зчитує та аналізує метадані конкретного скіла з файлу `main.json`.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/docs/escalation-log.md

@@ -3,25 +3,26 @@ type: JS Module
 title: escalation-log.mjs
 resource: npm/scripts/lib/fix/escalation-log.mjs
 docgen:
-  crc: 07ae959f
+  crc: 91898427
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Append-only JSONL-лог драбини ескалації конформність-фіксу. Один запис на рунг драбини: модель, чи виклик удався, чи правило стало зеленим після рунга («чи допомогло»), залишковий violation і само-аналіз моделі (`diagnosis`). Доповнює always-on wire-trace — той знає вміст викликів, але не результат re-check; join — за полем `caller` (`fix:<rule>:<rung>`).
+## Огляд
 
-## Поведінка
+Файл створює append-only JSONL-лог ескалації конформність-фіксу (спека 2026-06-19-fix-escalation-cascade-design). Він фіксує кожен запис на рунг драбини, що включає деталі використаної моделі (`model`), подання зворотного зв'язку (`withFeedback`), результат виклику (`callOk`/`callError`), оцінку, чи допомогло це усунути порушення (`recheckOk`), залишковий `violation` та самоаналіз моделі (`diagnosis`). Цей лог доповнює always-on wire-trace (`lib/pi-trace.mjs`) і формує логіку для join за полем `caller` (`fix:<rule>:<rung>`). Запис відбувається за певним шільною: або через kill-switch `N_CURSOR_FIX_ESCALATION_LOG`, або за явним шляхом, дефолтно у `<cwd>/.n-cursor/fix-escalation.jsonl`.
 
-`escalationLogPath` резолвить шлях: `N_CURSOR_FIX_ESCALATION_LOG` як kill-switch (`0|false|off|no` → лог вимкнено, повертає `null`) або як явний шлях; інакше дефолт `<cwd>/.n-cursor/fix-escalation.jsonl`.
+## Поведінка
 
-`logEscalation` дописує один JSONL-рядок (no-op, якщо лог вимкнено). Поля `remainingViolation` і `diagnosis` обрізаються до межі; `recheckOk` обнуляє `remainingViolation`. Помилки запису ковтаються — лог діагностичний і не має валити сам фікс.
+Поведінка:
+escalationLogPath визначає шлях до файлу журналу ескалації конформності. Якщо встановлено змінну середовища N_CURSOR_FIX_ESCALATION_LOG, використовується цей шлях; інакше, за замовчуванням, це .n-cursor/fix-escalation.jsonl у поточній робочій директорії.
+logEscalation записує один запис про рунг у JSONL-лог, якщо шлях до логу визначено. Запис містить метадані про спробу фіксування, результати виклику та аналіз. Помилки під час запису логу ігноруються.
 
 ## Публічний API
 
-- `escalationLogPath()` — шлях активного логу або `null`, якщо вимкнено.
-- `logEscalation(rec)` — дописує запис рунга у JSONL.
+escalationLogPath — вказує на місце зберігання логу ескалацій, якщо функція не вимкнена.
+logEscalation — записує один подію виконання в спеціальний лог у форматі JSONL, ігноруючи внутрішні помилки запису.
 
 ## Гарантії поведінки
 
-- Не звертається до мережі.
-- Перехоплює помилки запису і не пропускає винятків назовні (fail-safe).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).