@nitra/cursor 12.15.0 → 12.16.0

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/discover-checkable-rules.md

@@ -3,24 +3,24 @@ type: JS Module
 title: discover-checkable-rules.mjs
 resource: npm/scripts/lib/discover-checkable-rules.mjs
 docgen:
-  crc: 403ab2ee
+  crc: d06cd969
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Шукає правила, для яких є щось «прогонне» у визначених структурах. Виявляє JS-концерни за шляхами `rules/<id>/js/<concern>.mjs` та Policy-концерни, які мають пару з `<concern>.rego` (зв'язану з конфігурацією `target.json`). Ігнорує файли з префіксом `_` та `*.test.mjs`, а також каталоги `_lib/`. Виконання є швидким скануванням структури (шляхи та назви) без парсингу вмісту.
+Визначає наявність JS-концернів та policy-концернів у заданому каталозі правила. Сканує всі каталоги правил, шукаючи JS-концерни у файлах `rules/<id>/js/<concern>.mjs` та policy-концерни, що асоціюються з парою `<concern>.rego` та `target.json`. Повертає список правил, які містять такі прогонні частини. Файли з префіксом `_` або `*.test.mjs` ігноруються.
 
 ## Поведінка
 
-discoverOneRule описує набір JS-концернів та policy-концернів для одного каталогу правила, використовуючи шлях до цього каталогу та його ідентифікатор.
-discoverCheckableRules сканує каталог з усіма правилами та повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не містять прогонного контенту.
+discoverOneRule описує правило, виявляючи JS-концерни та policy-концерни в заданому каталозі правила.
+discoverCheckableRules сканує каталог правил і повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не мають прогонних частин.
 
 ## Публічний API
 
-discoverOneRule — створює об'єкт перевірки для одного каталогу правила.
-discoverCheckableRules — знаходити правила у каталозі `rules/`, які мають відповідні скрипти у `js/` або політики у `policy/`.
+- discoverOneRule — Створює об'єкт для одного правила, що перевіряє конкретний каталог.
+- discoverCheckableRules — Знаходить правила у каталозі `rules/`, які мають відповідні скрипти (у `js/`) або політики (у `policy/`). Ігнорує правила, що містять лише документацію.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/inline-template-links.md

@@ -3,22 +3,24 @@ type: JS Module
 title: inline-template-links.mjs
 resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  crc: e1bed533
+  crc: 252fb1e1
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль інтегрує зовнішній контент у текстовий вивід, використовуючи конфігурації з `package.json.snippet.json` та `package.json`. Він замінює посилання на шаблони в тексті на їхній вміст за допомогою `inlineTemplateLinks` та доповнює текст вмістом усіх знайдених файлів `.mdc` з директорій `js/` та `policy/<concern>/` за допомогою `appendDiscoveredMdcFiles`.
+## Огляд
+
+Модуль збагачує текстовий контент, використовуючи конфігурації з package.json.snippet.json та package.json. Функція inlineTemplateLinks замінює текстові посилання на шаблони вбудованими блоками, якщо відповідні файли знаходяться у директорії правил. Функція appendDiscoveredMdcFiles доповнює текст вмістом усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
 
 ## Поведінка
 
-inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом відповідних файлів.
-appendDiscoveredMdcFiles додає вміст усіх знайдених файлів \*.mdc з директорій js/ та policy/<concern>/ до наданого тексту.
+inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом файлу, якщо ці файли існують у вказаній директорії правил.
+appendDiscoveredMdcFiles додає до кінця тексту вміст усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
 
 ## Публічний API
 
-inlineTemplateLinks — Замінює посилання у Markdown, що містять `/template/`, на вбудовані блоки, зчитуючи вміст з вказаного файлу. Викидає помилку, якщо цільове посилання не знайдено.
-appendDiscoveredMdcFiles — Додає всі знайдені файли з розширенням `.mdc` з підкаталогів `js/` та `policy/<concern>/`. Спочатку додаються файли з `js/` (у алфавітному порядку), а потім файли з підкаталогів `policy/` (у алфавітному порядку за назвою `concern`, а потім за назвою файлу).
+inlineTemplateLinks — Замінює посилання на шаблони в Markdown на вбудовані блоки, якщо шлях містить `/template/`. Помилка виникає, якщо цільовий файл посилання відсутній.
+appendDiscoveredMdcFiles — Додає всі знайдені файли `.mdc` з папок `js/` та `policy/<concern>/`. Файли з `js/` йдуть першими, а потім файли з підпапок `policy/<concern>/` (у алфавітному порядку за `concern`, а потім за назвою файлу).
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -3,17 +3,19 @@ type: JS Module
 title: list-project-rules-mdc.mjs
 resource: npm/scripts/lib/list-project-rules-mdc.mjs
 docgen:
-  crc: 60cd4e83
+  crc: 59fe0e6e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Цей модуль визначає шлях до `.mdc`-файлів правил у проєкті-споживачі, що зберігаються у директорії, вказаній константою CURSOR_RULES_DIR. Він надає відсортований список імен цих файлів. Це винесення логіки з `bin/n-cursor.js` забезпечує розділення відповідальності між інструментом командного рядка та функцією перевірки конформності.
+## Огляд
+
+Цей модуль визначає шлях до правил у проєкті-споживачі, що константою експортується як CURSOR_RULES_DIR=".cursor/rules". Він надає відсортований список імен файлів `.mdc` з каталогу правил. Це дозволяє розділити логіку диспетчеризації командного інтерфейсу та логіку перевірки конформності. Функція зчитує та повертає список файлів, якщо каталог правил існує.
 
 ## Поведінка
 
 CURSOR_RULES_DIR — Вказує на каталог правил у проєкті-споживачі.
-listProjectRulesMdcFiles — Повертає відсортований список імен файлів з розширенням `.mdc` у каталозі правил проєкту, або порожній масив, якщо каталог не існує.
+listProjectRulesMdcFiles — Повертає відсортований список імен файлів `.mdc` з каталогу правил проєкту-споживача, якщо цей каталог існує.
 
 ## Публічний API
 

package/scripts/lib/docs/root-notice.md

@@ -3,30 +3,27 @@ type: JS Module
 title: root-notice.mjs
 resource: npm/scripts/lib/root-notice.mjs
 docgen:
-  crc: 5f3ca2bb
+  crc: 65db7d81
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл вставляє root-guard preflight для скілів, які змінюють проєкт у поточному каталозі. Він забезпечує, що скіл виконується in-place, без ізоляції worktree, і використовується для випадків, коли не потрібна ізоляція worktree. Це гарантує коректне виконання скілу від імені проєкту.
+## Огляд
+
+Цей модуль вшиває інструкцію для агента у файл `SKILL.md`. Інструкція вказує, що скіл мутує проєкт у поточному каталозі, але виконується in-place (без worktree-ізоляції), що відповідає конфігурації `meta.json` $\to$ `requireRoot: true` і `worktree: false`. Це застосовується до скілів, які змінюють `meta.json` або `package.json` безпосередньо, на відміну від worktree-скілів, які мають свій `root-assert` у `worktree-notice.mjs`. Блок є інструкцією агенту, що читає `SKILL.md`, і є ре-синк ідемпотентним: наявний блок замінюється, при `false` — видаляється. Програмний аналог для CLI-команд — `assertCwdIsProjectRoot`. Інструкція позначається маркерами `ROOT_START` ("<!-- n-cursor:root:start -->") та `ROOT_END` ("<!-- n-cursor:root:end -->").
 
 ## Поведінка
 
-ROOT_START: вставляє маркер початку root-блоку.
-ROOT_END: вставляє маркер кінця root-блоку.
-injectRootNotice: вставляє, оновлює або видаляє root-guard блок у вмісті `SKILL.md` на основі параметра `enabled`.
+ROOT_START: Позначає початок блоку інструкції щодо перевірки кореня репозиторію.
+ROOT_END: Позначає кінець блоку інструкції щодо перевірки кореня репозиторію.
+injectRootNotice: Вставляє, оновлює або видаляє блок інструкції щодо перевірки кореня репозиторію у вмісті файлу `SKILL.md` на основі булевого прапорця.
 
 ## Публічний API
 
-- ROOT_START — Позначає початок блоку root.
-- ROOT_END — Позначає кінець блоку root.
-- injectRootNotice — Змінює вміст `SKILL.md` щодо root-guard блоку.
+ROOT_START — маркер початку основного блоку документації.
+ROOT_END — маркер завершення основного блоку документації.
+injectRootNotice — додає, змінює або видаляє захисний блок у файлі `SKILL.md`.
 
 ## Гарантії поведінки
 
-- Якщо `requireRoot: true` у `meta.json`, то поточний робочий каталог є коренем проєкту.
-- Якщо `requireRoot: false`, то блок не вставляється.
-- Вставка відбувається лише між маркерами.
-- Вставка ре-синк ідемпотентно: наявний блок замінюється.
-- `ROOT_START` викликається перед вставкою блоку.
-- `ROOT_END` викликається після вставки блоку.
-- `injectRootNotice` викликається під час вставки блоку.
-- Немає кешування.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/run-lint.md

@@ -3,26 +3,28 @@ type: JS Module
 title: run-lint.mjs
 resource: npm/scripts/lib/run-lint.mjs
 docgen:
-  crc: f574f097
+  crc: 3c7deca0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує процесом лінтування коду. Він визначає набір активних правил лінтування, використовуючи конфігурації з `meta.json` та `.n-cursor.json`. Модуль надає можливість вибрати ці правила за допомогою `selectLintRules` та ініціювати запуск перевірки коду за допомогою `runLint`.
+## Огляд
+
+Модуль визначає набір правил лінтування, спираючись на конфігурації `meta.json` та `.n-cursor.json`. Він використовує `selectLintRules` для вибору та сортування цих правил, а потім ініціалізує процес перевірки конформності та форматування за допомогою `runLint` у різних режимах (scoped, hook, delta, full).
 
 ## Поведінка
 
-selectLintRules визначає, які правила лінтуються на основі їхньої конфігурації та активності в `.n-cursor.json`, повертаючи відсортований список ID.
-runLint запускає лінтер-оркестрацію залежно від наданих опцій: виконує прогін для конкретних правил, перевіряє лише змінені файли, виконує повний прогін репозиторію або форматування.
+selectLintRules вибирає і алфавітно сортує ідентифікатори правил для лінтування на основі їхньої метаінформації та стану активації в `.n-cursor.json`.
+runLint запускає лінт-оркестрацію, виконуючи різні режими залежно від наданих опцій: scoped (за назвами правил), hook (за явним списком файлів), delta (зміна відносно origin) або full (весь репозиторій), включаючи конформність та форматування у fix-режимі.
 
 ## Публічний API
 
-selectLintRules — вибирає ідентифікатори правил для контексту в алфавітному порядку.
+selectLintRules — обирає ідентифікатори правил для контексту, у алфавітному порядку.
 runLint — ініціює процес лінтування.
 full — аналізує весь репозиторій, порівнюючи поточний стан із початковим.
-readOnly — лише виявляє проблеми, не вносячи змін.
-rules — виконує повний прогін лише для заданого набору правил у вказаному контексті.
-files — виконує перевірку лише для перелічених файлів у режимі хука.
+readOnly — лише виявляє проблеми без внесення змін.
+rules — виконує повний прогін лише для заданого набору правил.
+files — застосовує правила до конкретного переліку файлів у режимі хука.
 
 ## Гарантії поведінки
 

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

@@ -3,26 +3,45 @@ type: JS Module
 title: skill-meta.mjs
 resource: npm/scripts/lib/skill-meta.mjs
 docgen:
-  crc: c1757867
+  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`. Цей файл є єдиним джерелом правди для скіла. Модуль дозволяє визначати умови автоактивації скіла (через поле `auto`), вказувати, чи виконувати скіл в окремому git-worktree (`worktree`), та чи вимагає він запуску з кореня репозиторію (`requireRoot`). Надає константу `SKILL_ALWAYS` для безумовної активації. Хелпер використовується іншими компонентами для уникнення дублювання парсингу. Функції забезпечують перехоплення помилок (fail-safe), повертаючи порожнє значення замість винятків.
+## Огляд
+
+Спільний парсер метаданих скіла з `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` для заданого каталогу скіла.
+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` у структуру `SkillAutoSpec`.
-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/discover-t0-patterns.md

@@ -3,28 +3,25 @@ type: JS Module
 title: discover-t0-patterns.mjs
 resource: npm/scripts/lib/fix/discover-t0-patterns.mjs
 docgen:
-  crc: f2a262bb
+  crc: 3f3b47e0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль сканує директорію правил для пошуку файлів `fix-*.mjs`, що містять визначення T0-паттернів. Він динамічно імпортує ці файли з папок `js` та `policy/{concern}` для кожного правила. Ініціалізація результату відбувається за допомогою _top-level await_ у `t0.mjs`. Функція збирає масив об'єктів, що описують усі знайдені паттерни.
+Сканує директорії `npm/rules/{rule}/js/fix-*.mjs` та `npm/rules/{rule}/policy/{concern}/fix-*.mjs` для всіх правил. Динамічно імпортує кожен знайдений файл `fix-*.mjs` та збирає масиви `patterns`. Результат ініціалізується через top-level await у `t0.mjs` і представляє унікальний список усіх виявлених T0-паттернів. Функція не виконує операцій запису та перехоплює помилки, повертаючи `null` у випадку збоїв замість викидання винятків.
 
 ## Поведінка
 
-1. Перевіряє існування директорії, вказаної як `rulesDir`. Якщо директорія не існує, повертає порожній масив.
-2. Зчитує список усіх елементів у директорії `rulesDir`.
-3. Для кожного елемента, який є директорією та не починається з крапки, виконується наступне:
-   а. Визначається повний шлях до директорії правила.
-   б. Знаходяться всі файли `fix-*.mjs` у піддиректорії `js` цього правила.
-   в. Знаходяться всі файли `fix-*.mjs` у піддиректоріях `policy/{concern}` цього правила.
-   г. Для кожного знайденого файлу `fix-*.mjs` виконується динамічний імпорт.
-   д. Якщо імпорт успішний, збирається масив `patterns` з імпортованого модуля та додається до загального списку паттернів.
-   е. У разі помилки імпорту, помилка виводиться в консоль, але процес продовжується.
-4. Після обробки всіх правил, виконується дедуплікація загального списку паттернів за їхніми ідентифікаторами.
-5. Повертається фінальний, унікальний масив T0-паттернів.
+1. Перевіряє існування шляху `rulesDir`. Якщо шлях не існує, повертає порожній масив.
+2. Знаходить усі файли з шаблонами у шляхах `*/js/fix-*.mjs` та `*/policy/*/fix-*.mjs` у межах `rulesDir`.
+3. Для кожного знайденого файлу:
+   а. Намагається динамічно імпортувати вміст файлу.
+   б. Якщо імпорт успішний і вміст містить масив `patterns`, додає ці паттерни до загального списку.
+   в. Якщо імпорт не вдається, реєструє помилку, але продовжує роботу.
+4. Фільтрує загальний список паттернів, щоб уникнути дублікатів, зберігаючи лише перше входження кожного паттерна за його ідентифікатором.
+5. Повертає відфільтрований масив унікальних T0-паттернів.
 
 ## Публічний API
 

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).

package/scripts/lib/fix/docs/index.md

@@ -8,7 +8,6 @@ resource: npm/scripts/lib/fix/
 
 | Файл                                                  | Тип       |
 | ----------------------------------------------------- | --------- |
-| [analyze-escalation.mjs](analyze-escalation.md)       | JS Module |
 | [discover-t0-patterns.mjs](discover-t0-patterns.md)   | JS Module |
 | [escalation-log.mjs](escalation-log.md)               | JS Module |
 | [llm-fix-apply.mjs](llm-fix-apply.md)                 | JS Module |