@nitra/cursor 5.2.1 → 5.3.1

package/scripts/worktree-cli.mjs

@@ -79,7 +79,7 @@ function listDescFiles(cwd) {
 /**
  * add: створити worktree від HEAD + .md-опис.
  * @param {string[]} rest [branch, ...descParts]
- * @param {{ cwd: string, log: Function, logError: Function, now: () => Date }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void, logError: (line: string) => void, now: () => Date }} ctx контекст
  * @returns {number} exit code
  */
 function cmdAdd(rest, ctx) {
@@ -135,7 +135,7 @@ function cmdAdd(rest, ctx) {
 /**
  * remove: прибрати checkout + .md (гілку лишає).
  * @param {string[]} rest [branch, ...flags]
- * @param {{ cwd: string, log: Function, logError: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void, logError: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdRemove(rest, ctx) {
@@ -167,7 +167,7 @@ function cmdRemove(rest, ctx) {
 
 /**
  * list: git worktree list + вміст .md-описів.
- * @param {{ cwd: string, log: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdList(ctx) {
@@ -181,7 +181,7 @@ function cmdList(ctx) {
 
 /**
  * prune: git worktree prune + видалити осиротілі .md.
- * @param {{ cwd: string, log: Function }} ctx контекст
+ * @param {{ cwd: string, log: (line: string) => void }} ctx контекст
  * @returns {number} exit code
  */
 function cmdPrune(ctx) {
@@ -198,7 +198,7 @@ function cmdPrune(ctx) {
 /**
  * Точка входу підкоманди worktree.
  * @param {string[]} argv аргументи після `worktree`
- * @param {{ cwd?: string, log?: Function, logError?: Function, now?: () => Date }} [options] ін'єкція для тестів
+ * @param {{ cwd?: string, log?: (line: string) => void, logError?: (line: string) => void, now?: () => Date }} [options] ін'єкція для тестів
  * @returns {Promise<number>} exit code
  */
 export function runWorktreeCli(argv, options = {}) {

package/skills/doc-files/js/docgen-extract.mjs

@@ -65,7 +65,7 @@ function cleanJsDoc(raw) {
 }
 
 /**
- * Опис (без @-тегів) + параметри з @param як «name — опис».
+ * Опис (без @-тегів) + параметри з `@param` як «name — опис».
  * @param {string} raw сирий JSDoc-блок
  * @returns {{desc:string, params:Array<{name:string, desc:string}>, ret:string}} розпарсений опис, параметри й опис повернення
  */

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

@@ -79,6 +79,68 @@ function preflightProblem() {
   return `omlx помилка: ${hc.detail}`
 }
 
+/**
+ * Текст-суфікс режиму для прогрес-рядка.
+ * @param {{ overwrite: boolean, retryDegraded: boolean }} mode режими
+ * @returns {string} ` (--overwrite)` / ` (--retry-degraded)` / порожній рядок
+ */
+function modeSuffix({ overwrite, retryDegraded }) {
+  if (overwrite) return ' (--overwrite)'
+  if (retryDegraded) return ' (--retry-degraded)'
+  return ''
+}
+
+/**
+ * Генерує й штампує доку для одного файлу, оновлюючи лічильники й прогрес.
+ * @param {object} file елемент scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ done: number, total: number }} progress позиція у прогресі
+ * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats акумулятор статистики
+ * @returns {Promise<void>}
+ */
+async function generateOne(file, root, progress, stats) {
+  const sourceAbs = join(root, file.sourcePath)
+  process.stdout.write(`  [${progress.done}/${progress.total}] ${file.sourcePath} … `)
+  try {
+    const docAbs = join(root, file.docPath)
+    // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
+    const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
+    const result = await generateDoc(sourceAbs, { existingMd })
+    const crc = crc32(readFileSync(sourceAbs))
+    mkdirSync(dirname(docAbs), { recursive: true })
+    const quality =
+      result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
+    writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
+    stats.ok++
+    if (result.degraded) {
+      stats.degraded++
+      process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
+    } else {
+      process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
+    }
+  } catch (error) {
+    stats.err++
+    stats.errors.push(file.sourcePath)
+    process.stdout.write(`✗ ${error.message}\n`)
+  }
+}
+
+/**
+ * Підсумковий звіт прогону у stdout.
+ * @param {{ ok: number, degraded: number, err: number, errors: string[] }} stats статистика
+ * @returns {void}
+ */
+function reportStats(stats) {
+  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
+  if (stats.errors.length > 0) {
+    console.log('Помилки:')
+    for (const e of stats.errors) console.log(`  - ${e}`)
+  }
+  if (stats.degraded > 0) {
+    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
+  }
+}
+
 /**
  * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
  * @param {string[]} argv аргументи після назви субкоманди
@@ -106,47 +168,16 @@ export async function runDocFilesGenCli(argv) {
     return 1
   }
 
-  let modeTxt = ''
-  if (overwrite) modeTxt = ' (--overwrite)'
-  else if (retryDegraded) modeTxt = ' (--retry-degraded)'
-  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeTxt}`)
+  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`)
   const stats = { ok: 0, degraded: 0, err: 0, errors: [] }
 
   let done = 0
   for (const file of targets) {
     done++
-    const sourceAbs = join(root, file.sourcePath)
-    process.stdout.write(`  [${done}/${targets.length}] ${file.sourcePath} … `)
-    try {
-      const result = await generateDoc(sourceAbs)
-      const crc = crc32(readFileSync(sourceAbs))
-      const docAbs = join(root, file.docPath)
-      mkdirSync(dirname(docAbs), { recursive: true })
-      const quality =
-        result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
-      writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality))
-      stats.ok++
-      if (result.degraded) {
-        stats.degraded++
-        process.stdout.write(`⚠ degraded score=${result.score} crc=${crc}\n`)
-      } else {
-        process.stdout.write(`✓ score=${result.score ?? '—'} crc=${crc}\n`)
-      }
-    } catch (error) {
-      stats.err++
-      stats.errors.push(file.sourcePath)
-      process.stdout.write(`✗ ${error.message}\n`)
-    }
+    await generateOne(file, root, { done, total: targets.length }, stats)
   }
 
-  console.log(`\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}`)
-  if (stats.errors.length > 0) {
-    console.log('Помилки:')
-    for (const e of stats.errors) console.log(`  - ${e}`)
-  }
-  if (stats.degraded > 0) {
-    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor doc-files gen --retry-degraded`)
-  }
+  reportStats(stats)
   return stats.err > 0 ? 1 : 0
 }
 

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

@@ -1,11 +1,12 @@
 /** @see ./docs/docgen-gen.md */
-import { readFileSync } from 'node:fs'
+import { readFileSync, existsSync } from 'node:fs'
 import { basename } from 'node:path'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
 import { DEFAULT_OMLX_MODEL } from '../../../lib/omlx.mjs'
 import { callLlm } from '../../../lib/llm.mjs'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { docPathForSource } from './docgen-scan.mjs'
 import { extractFacts } from './docgen-extract.mjs'
 import { extractAnchors, anchorTokens } from './docgen-extract-anchors.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
@@ -26,15 +27,28 @@ const SECTION_KEY_CLEAN_RE = /[^а-яіїєґa-z0-9]/gi
 const CACHE_MENTION_RE = /кеш/i
 const CACHE_NEGATION_RE = /(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i
 const CRITIC_NONE_RE = /^\s*NONE\s*$/i
-// R4: абстрактні «нічого-не-кажучі» формули, які обходять exact-blocklist і дають score=100
-const GENERIC_RE =
-  /відповідност\S*\s+(?:даних\s+)?(?:визначеному\s+)?контракту|валідаці\S*\s+даних|перевірк\S*\s+(?:відповідності\s+)?даних|обробк\S*\s+даних|застосову\S*\s+логіку|інспекту\S*\s+та\s+збира\S*\s+дан/i
+// R4: абстрактні «нічого-не-кажучі» формули, які обходять exact-blocklist і дають score=100.
+// Масив дрібних патернів замість однієї alternation-regex (sonarjs/regex-complexity); .some() еквівалентний.
+const GENERIC_RES = [
+  /відповідност\S*\s+(?:даних\s+)?(?:визначеному\s+)?контракту/i,
+  /валідаці\S*\s+даних/i,
+  /перевірк\S*\s+(?:відповідності\s+)?даних/i,
+  /обробк\S*\s+даних/i,
+  /застосову\S*\s+логіку/i,
+  /інспекту\S*\s+та\s+збира\S*\s+дан/i
+]
 // R7: часті русизми/суржик (курований безпечний список — без false-positive на нормальній мові).
 // Без \b: кирилиця не є ASCII-`\w`, тож межі слова в JS-regex не спрацьовують — терміни специфічні.
 const SURZHIK_RE =
   /пропуская|являється|в залежності|по замовчуванню|на протязі|відповідаюч|слідуюч|наступним разом|приймати участь|у відповідності/i
 const ANCHOR_MISS_PENALTY = 5
 const ANCHOR_MISS_CAP = 20
+// Захищена людино-керована секція (Варіант B): дослівно зберігається, ніколи не
+// перезаписується LLM-виходом, виключена зі скорингу. Opt-in = сам факт наявності.
+const PROTECTED_HEADING = 'Призначення'
+const PROTECTED_START_RE = /^##\s+Призначення\s*$/
+const H2_RE = /^##\s/
+const H1_RE = /^#\s/
 
 /**
  * Прибирає код-фенс-обгортку (потрійні бектіки) й випадковий провідний
@@ -82,6 +96,43 @@ function parseSections(md) {
   return result
 }
 
+/**
+ * Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## `
+ * (H2); `###`+ усередині не обривають блок.
+ * @param {string} md документ
+ * @returns {{ body: string|null, without: string }} тіло блоку (або null) і md без нього
+ */
+export function splitProtected(md) {
+  const lines = md.split('\n')
+  const start = lines.findIndex(l => PROTECTED_START_RE.test(l))
+  if (start === -1) return { body: null, without: md }
+  let end = lines.length
+  for (let i = start + 1; i < lines.length; i++) {
+    if (H2_RE.test(lines[i])) {
+      end = i
+      break
+    }
+  }
+  const body = lines.slice(start + 1, end).join('\n').trim()
+  const without = [...lines.slice(0, start), ...lines.slice(end)].join('\n')
+  return { body: body || null, without }
+}
+
+/**
+ * Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція).
+ * @param {string} md машинно-згенерований документ (без блоку)
+ * @param {string|null} intent тіло блоку або null
+ * @returns {string} документ із блоком (або без змін, якщо intent порожній)
+ */
+export function insertProtected(md, intent) {
+  if (!intent) return md
+  const lines = md.split('\n')
+  const h1 = lines.findIndex(l => H1_RE.test(l))
+  const at = h1 === -1 ? 0 : h1 + 1
+  lines.splice(at, 0, '', `## ${PROTECTED_HEADING}`, '', intent)
+  return lines.join('\n')
+}
+
 /**
  * Чи містить текст бектік-обгорнуте імʼя символу (`sym`) — уникає substring false positives.
  * @param {string} text текст секції
@@ -92,6 +143,45 @@ function hasName(text, sym) {
   return text.includes('`' + sym + '`')
 }
 
+/**
+ * R6: штраф за службові (неекспортовані) символи, подані як публічні.
+ * @param {object} facts факт-лист про файл
+ * @param {{ overview: string, behavior: string, api: string, guarantees: string }} secs тексти секцій
+ * @param {string[]} issues акумулятор кодів проблем (мутується)
+ * @returns {number} сумарний штраф (≥0)
+ */
+function internalSymbolPenalty(facts, { overview, behavior, api, guarantees }, issues) {
+  let penalty = 0
+  for (const sym of [...(facts.internalSymbols ?? []), ...(facts.localSymbols ?? [])]) {
+    const inDoc = hasName(guarantees, sym) || hasName(overview, sym) || hasName(behavior, sym) || hasName(api, sym)
+    if (inDoc) {
+      penalty += 10
+      issues.push(`internal-name:${sym}`)
+    }
+  }
+  return penalty
+}
+
+/**
+ * R5: штраф за відсутні в документі валідні анкори (дослівні підрядки src).
+ * @param {string} md зібраний документ
+ * @param {object} anchors анкори файлу
+ * @param {string} src вміст файлу
+ * @param {string[]} issues акумулятор кодів проблем (мутується)
+ * @returns {number} штраф, обмежений ANCHOR_MISS_CAP
+ */
+function anchorMissPenalty(md, anchors, src, issues) {
+  let penalty = 0
+  for (const tok of anchorTokens(anchors)) {
+    if (!src.includes(tok)) continue // валідність: фейковий анкор не вимагаємо
+    if (!md.includes(tok) && penalty < ANCHOR_MISS_CAP) {
+      penalty += ANCHOR_MISS_PENALTY
+      issues.push(`anchor-miss:${tok}`)
+    }
+  }
+  return penalty
+}
+
 /**
  * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
  * @param {string} md зібраний документ
@@ -111,7 +201,7 @@ export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
   }
 
   // R4: generic-Огляд (парафрази, які обходять exact-blocklist) — як майже-відсутній.
-  if (GENERIC_RE.test(overview)) {
+  if (GENERIC_RES.some(re => re.test(overview))) {
     score -= 35
     issues.push('generic-overview')
   }
@@ -133,29 +223,15 @@ export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
 
   // R6: службові (неекспортовані) функції не мають фігурувати як публічні
   const api = s['публічнийapi'] ?? ''
-  for (const sym of [...(facts.internalSymbols ?? []), ...(facts.localSymbols ?? [])]) {
-    const inDoc = hasName(guarantees, sym) || hasName(overview, sym) || hasName(behavior, sym) || hasName(api, sym)
-    if (inDoc) {
-      score -= 10
-      issues.push(`internal-name:${sym}`)
-    }
-  }
+  score -= internalSymbolPenalty(facts, { overview, behavior, api, guarantees }, issues)
 
   // R5: кожен валідний анкор (дослівний підрядок src) має зʼявитися в документі
   if (anchors && src) {
-    let missPenalty = 0
-    for (const tok of anchorTokens(anchors)) {
-      if (!src.includes(tok)) continue // валідність: фейковий анкор не вимагаємо
-      if (!md.includes(tok) && missPenalty < ANCHOR_MISS_CAP) {
-        missPenalty += ANCHOR_MISS_PENALTY
-        issues.push(`anchor-miss:${tok}`)
-      }
-    }
-    score -= missPenalty
+    score -= anchorMissPenalty(md, anchors, src, issues)
   }
 
-  // R7: суржик/русизми
-  if (SURZHIK_RE.test(md)) {
+  // R7: суржик/русизми — лише в машинних секціях (захищене «Призначення» — людське, не штрафуємо)
+  if (SURZHIK_RE.test(splitProtected(md).without)) {
     score -= 10
     issues.push('surzhik')
   }
@@ -199,13 +275,14 @@ function apiNeedsRefine(facts) {
  * @param {string} src вміст файлу
  * @param {string} model model-id
  * @param {number} [timeoutMs] ліміт на виклик
+ * @param {{ intent?: string|null }} [opts] захищена секція «Призначення» для збереження
  * @returns {{ md: string }} зібраний документ
  */
-function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS) {
+function oneShotDoc(facts, src, model, timeoutMs = LOCAL_TIMEOUT_MS, { intent = null } = {}) {
   const text = callLlm(oneShotMessages(facts, src), model, { timeoutMs })
   let md = stripSignatures(stripSection(text))
   if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
-  return { md: md + '\n' }
+  return { md: insertProtected(md + '\n', intent) }
 }
 
 /**
@@ -236,16 +313,16 @@ function assemble(stem, sections) {
  * @param {string} src вміст файлу
  * @param {string} model model-id
  * @param {number} timeoutMs ліміт на один виклик
- * @param {{ anchors?: object|null, temperature?: number }} [opts] анкори й температура семплінгу
+ * @param {{ anchors?: object|null, temperature?: number, intent?: string|null }} [opts] анкори, температура, захищена секція як контекст
  * @returns {{ md: string }} зібраний документ
  */
-function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, temperature = 0.2 } = {}) {
+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)) {
+  for (const s of sectionMessages(facts, src, anc, intent)) {
     let draft = stripSignatures(stripSection(callLlm(s.messages, model, { timeoutMs, temperature })))
     // E2: critique→refine для API, коли всі описи порожні (модель зриває на generic)
     if (s.key === 'api' && apiNeedsRefine(facts)) {
@@ -255,11 +332,14 @@ function orchestratedDoc(facts, src, model, timeoutMs, { anchors = null, tempera
   }
   // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
   let overview = stripSignatures(
-    stripSection(callLlm(overviewMessages(facts, sections.behavior ?? '', anc), model, { timeoutMs, temperature }))
+    stripSection(
+      callLlm(overviewMessages(facts, sections.behavior ?? '', anc, intent), model, { timeoutMs, temperature })
+    )
   )
   overview = critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
   sections.overview = overview
-  return { md: assemble(basename(facts.relPath), sections) }
+  // Варіант B: дослівно повертаємо захищений блок у фіксовану позицію
+  return { md: insertProtected(assemble(basename(facts.relPath), sections), intent) }
 }
 
 /** Максимальний час генерації одного LLM-виклику. */
@@ -279,18 +359,20 @@ export const DEFAULT_LOCAL_MODEL = env.N_CURSOR_DOCGEN_MODEL ?? (resolveModel('m
  * з вищою температурою (best-of-2); якщо й він не допоміг — результат
  * позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
  * @param {string} file абсолютний шлях джерела
- * @param {{ model?: string, threshold?: number }} [opts] model-id і поріг degraded
+ * @param {{ model?: string, threshold?: number, existingMd?: string|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції)
  * @returns {{ md: string, ms: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації
  */
-export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD } = {}) {
+export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null } = {}) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
 
+  // Варіант B: захищена секція «Призначення» з наявної доки — зберегти й подати як контекст
+  const intent = existingMd ? splitProtected(existingMd).body : null
   const anchors = facts.unsupported ? null : extractAnchors(src)
   let r = facts.unsupported
-    ? oneShotDoc(facts, src, model)
-    : orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors })
+    ? oneShotDoc(facts, src, model, LOCAL_TIMEOUT_MS, { intent })
+    : orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, intent })
 
   // unsupported (vue/py до юніт-шару): скорер не застосовний — score=null, не degraded
   if (facts.unsupported) {
@@ -303,7 +385,7 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
   // 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 })
+      const r2 = 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
@@ -329,7 +411,10 @@ if (isRunAsCli(import.meta.url)) {
   if (!file) {
     throw new Error('Usage: node docgen-gen.mjs <file> [--model <m>]')
   }
-  const r = generateDoc(file, { model })
+  // Зберегти захищену секцію «Призначення», якщо дока вже існує
+  const docPath = docPathForSource(file)
+  const existingMd = existsSync(docPath) ? readFileSync(docPath, 'utf8') : null
+  const r = generateDoc(file, { model, existingMd })
   const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
   process.stderr.write(`[local ${r.model}] ${r.ms}ms / score=${r.score}${r.degraded ? ' DEGRADED' : ''}${issuesTxt}\n`)
   process.stdout.write(r.md)

package/skills/doc-files/js/docgen-prompts.mjs

@@ -50,6 +50,17 @@ const msgs = (system, user) => [
   { role: 'user', content: user }
 ]
 
+/**
+ * Блок read-only авторитетного контексту із захищеної секції «Призначення»
+ * (Варіант B): машинні секції мають узгоджуватися з ним і НЕ дублювати його.
+ * @param {string|null} intent тіло секції «Призначення» або null
+ * @returns {string} текстовий блок для system-промпта або порожній рядок
+ */
+function intentContext(intent) {
+  if (!intent) return ''
+  return `\n\nАВТОРИТЕТНИЙ КОНТЕКСТ (секція «Призначення», написана людиною — НЕ повторюй дослівно, узгоджуйся й доповнюй):\n${intent}`
+}
+
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
  * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
@@ -57,11 +68,13 @@ const msgs = (system, user) => [
  * @param {object} facts факт-лист про файл
  * @param {string} src вміст файлу
  * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
+ * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
  * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
  */
-export function sectionMessages(facts, src, anchors = null) {
+export function sectionMessages(facts, src, anchors = null, intent = null) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
+  const intentCtx = intentContext(intent)
   const multi = (facts.exports?.length || 0) > 1
 
   // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
@@ -79,7 +92,7 @@ export function sectionMessages(facts, src, anchors = null) {
     key: 'behavior',
     numPredict: 500,
     messages: msgs(
-      `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
+      `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentCtx}`,
       `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
     )
   }
@@ -104,14 +117,16 @@ export function sectionMessages(facts, src, anchors = null) {
  * @param {object} facts факт-лист про файл
  * @param {string} behaviorText готовий текст секції «Поведінка»
  * @param {object|null} [anchors] анкори файлу
+ * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
  * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
  */
-export function overviewMessages(facts, behaviorText, anchors = null) {
+export function overviewMessages(facts, behaviorText, anchors = null, intent = null) {
   const factsTxt = factsSummary(facts)
   const anch = anchorsBlock(anchors)
+  const dedup = intent ? ' Не дублюй секцію «Призначення».' : ''
   return msgs(
-    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}`,
-    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.\n\nПОВЕДІНКА:\n${behaviorText}`
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentContext(intent)}`,
+    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.${dedup}\n\nПОВЕДІНКА:\n${behaviorText}`
   )
 }
 

package/skills/fix/js/llm-worker.mjs

@@ -2,10 +2,9 @@
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { spawnSync } from 'node:child_process'
 import { env } from 'node:process'
 import { resolveModel } from '../../../lib/models.mjs'
-import { callOmlx, isOmlxModel } from '../../../lib/omlx.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
 
 // Тир за замовчуванням: min → avg при ескалації (каскад local→cloud).
 // Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
@@ -13,6 +12,7 @@ export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
 const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
+const API_KEY_RE = /api key/i
 
 /**
  * Витягує відносні шляхи файлів із violation output.
@@ -87,29 +87,18 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
 }
 
 /**
- * Викликає LLM за model-id і повертає текст відповіді.
- * `omlx/...` → прямий HTTP до omlx (text-only, локально); решта → pi CLI.
+ * Викликає LLM через спільний `callLlm` (маршрут за префіксом model-id; wire-trace).
+ * Зберігає дружнє повідомлення про відсутній API-ключ для хмарних провайдерів.
  * @param {string} prompt текст промпта
  * @param {string} model назва моделі (provider/id, `omlx/...` або '')
  * @returns {{ text: string, error?: string }} текст відповіді або повідомлення про помилку
  */
 function callModel(prompt, model) {
-  if (isOmlxModel(model)) {
-    try {
-      return { text: callOmlx([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000 }) }
-    } catch (error) {
-      return { text: '', error: error.message }
-    }
-  }
-  const modelArgs = model ? ['--model', model] : []
-  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
-    encoding: 'utf8',
-    timeout: 120_000
-  })
-  if (r.error) return { text: '', error: r.error.message }
-  if (r.status !== 0) {
-    const stderr = r.stderr?.slice(0, 300) ?? ''
-    if (stderr.toLowerCase().includes('no api key') || stderr.toLowerCase().includes('api key')) {
+  try {
+    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller: 'fix' }) }
+  } catch (error) {
+    const msg = String(error.message)
+    if (API_KEY_RE.test(msg)) {
       const provider = model ? model.split('/')[0] : 'дефолтного провайдера'
       return {
         text: '',
@@ -120,9 +109,8 @@ function callModel(prompt, model) {
         ].join(' ')
       }
     }
-    return { text: '', error: `pi exit ${r.status}: ${stderr}` }
+    return { text: '', error: msg }
   }
-  return { text: r.stdout?.trim() ?? '' }
 }
 
 /**