@nitra/cursor 5.3.0 → 5.3.2

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-ignore.mjs

@@ -5,6 +5,7 @@ import picomatch from 'picomatch'
 export const DOCGEN_IGNORE_GLOBS = Object.freeze([
   '**/node_modules/**',
   '**/dist/**',
+  '**/target/**',
   '.git/**',
   '**/__pycache__/**',
   '**/coverage/**',

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/doc-files/js/docgen-scan.mjs

@@ -11,7 +11,7 @@ import { isDocgenIgnored } from './docgen-ignore.mjs'
 import { QUALITY_THRESHOLD, readDocQuality, staleness } from './docgen-crc.mjs'
 
 /** Кодові розширення, для яких генеруємо документацію. */
-const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
+const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py', '.rs'])
 
 /** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u

package/skills/fix/js/orchestrator.mjs

@@ -11,18 +11,74 @@ const DEFAULT_MAX_ITER = 3
 const ESCALATE_AFTER = 2
 
 /**
- * @param {string[]} args   CLI аргументи після 'fix'
- * @param {string}   cwd    корінь проєкту
- * @returns {Promise<number>}  0 = all clean, 1 = unresolved
+ * Парсить `--max-iter N` і збирає rule-filter (позиційні аргументи без прапорців).
+ * @param {string[]} args CLI аргументи після 'fix'
+ * @returns {{ maxIter: number, ruleFilter: string[] }} ліміт ітерацій і фільтр правил
  */
-export async function runOrchestratorCli(args, cwd) {
-  const { runLlmWorker, MODEL, MODEL_HEAVY } = await import('./llm-worker.mjs')
-
+function parseOrchestratorArgs(args) {
   const maxIterIdx = args.indexOf('--max-iter')
   const maxIter =
     maxIterIdx === -1 ? DEFAULT_MAX_ITER : Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER
   const skipIdxs = new Set(maxIterIdx === -1 ? [] : [maxIterIdx, maxIterIdx + 1])
   const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
+  return { maxIter, ruleFilter }
+}
+
+/**
+ * Крок T0-auto: детермінований фікс без LLM, повертає правила, що лишились.
+ * @param {string} cwd корінь проєкту
+ * @param {string[]} ruleFilter фільтр правил
+ * @param {Array<{ ruleId: string }>} failed правила перед кроком
+ * @returns {Array<{ ruleId: string, ok: boolean, output: string }>} правила після T0
+ */
+function runT0Step(cwd, ruleFilter, failed) {
+  spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'pipe' })
+
+  const afterT0 = runFixCheck(cwd, ruleFilter)
+  const failedAfterT0 = afterT0?.rules.filter(r => !r.ok) ?? failed
+  const t0Fixed = failed.filter(r => !failedAfterT0.some(f => f.ruleId === r.ruleId))
+
+  if (t0Fixed.length > 0) {
+    console.log(`  ⚙️  T0-auto: ${t0Fixed.map(r => r.ruleId).join(', ')}`)
+  }
+  return failedAfterT0
+}
+
+/**
+ * Крок T1: LLM через pi для кожного правила, з ескалацією моделі за провалами.
+ * @param {Array<{ ruleId: string, output: string }>} failed правила до фіксу
+ * @param {string} cwd корінь проєкту
+ * @param {Map<string, number>} failCount ruleId → кількість провалів підряд (мутується)
+ * @param {{ runLlmWorker: (ruleId: string, output: string, projectRoot: string, opts: {model: string}) => Promise<{ok: boolean, error?: string}>, MODEL: string, MODEL_HEAVY: string }} worker воркер і моделі
+ * @returns {Promise<void>}
+ */
+async function runLlmStep(failed, cwd, failCount, { runLlmWorker, MODEL, MODEL_HEAVY }) {
+  for (const rule of failed) {
+    const prevFails = failCount.get(rule.ruleId) ?? 0
+    const model = prevFails >= ESCALATE_AFTER ? MODEL_HEAVY : MODEL
+    const label = model || 'pi'
+
+    const result = await runLlmWorker(rule.ruleId, rule.output, cwd, { model })
+
+    if (result.ok) {
+      console.log(`  ⚡ LLM (${label}): ${rule.ruleId}`)
+      failCount.delete(rule.ruleId)
+    } else {
+      failCount.set(rule.ruleId, prevFails + 1)
+      const hint = (result.error ?? '').slice(0, 200)
+      console.log(`  ⚡ LLM (${label}): ${rule.ruleId} ❌  ${hint}`)
+    }
+  }
+}
+
+/**
+ * @param {string[]} args   CLI аргументи після 'fix'
+ * @param {string}   cwd    корінь проєкту
+ * @returns {Promise<number>}  0 = all clean, 1 = unresolved
+ */
+export async function runOrchestratorCli(args, cwd) {
+  const worker = await import('./llm-worker.mjs')
+  const { maxIter, ruleFilter } = parseOrchestratorArgs(args)
 
   /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
   const failCount = new Map()
@@ -48,37 +104,10 @@ export async function runOrchestratorCli(args, cwd) {
   if (ruleFilter.length) console.log(`   filter: ${ruleFilter.join(', ')}`)
 
   for (let iter = 1; iter <= maxIter; iter++) {
-    // ── T0-auto: детермінований фікс без LLM ──
-    spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'pipe' })
-
-    const afterT0 = runFixCheck(cwd, ruleFilter)
-    const failedAfterT0 = afterT0?.rules.filter(r => !r.ok) ?? failed
-    const t0Fixed = failed.filter(r => !failedAfterT0.some(f => f.ruleId === r.ruleId))
-
-    if (t0Fixed.length > 0) {
-      console.log(`  ⚙️  T0-auto: ${t0Fixed.map(r => r.ruleId).join(', ')}`)
-    }
-
-    failed = failedAfterT0
+    failed = runT0Step(cwd, ruleFilter, failed)
     if (failed.length === 0) break
 
-    // ── T1: LLM через pi ──
-    for (const rule of failed) {
-      const prevFails = failCount.get(rule.ruleId) ?? 0
-      const model = prevFails >= ESCALATE_AFTER ? MODEL_HEAVY : MODEL
-      const label = model || 'pi'
-
-      const result = await runLlmWorker(rule.ruleId, rule.output, cwd, { model })
-
-      if (result.ok) {
-        console.log(`  ⚡ LLM (${label}): ${rule.ruleId}`)
-        failCount.delete(rule.ruleId)
-      } else {
-        failCount.set(rule.ruleId, prevFails + 1)
-        const hint = (result.error ?? '').slice(0, 200)
-        console.log(`  ⚡ LLM (${label}): ${rule.ruleId} ❌  ${hint}`)
-      }
-    }
+    await runLlmStep(failed, cwd, failCount, worker)
 
     // Перевірка після LLM
     const afterLLM = runFixCheck(cwd, ruleFilter)

package/skills/fix/js/t0.mjs

@@ -113,6 +113,43 @@ const HERE = dirname(fileURLToPath(import.meta.url))
 /** Абсолютний шлях до npm/bin/n-cursor.js відносно цього файлу */
 const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
 
+/**
+ * Запускає `_fix-check` і парсить JSON-результат.
+ * @param {string[]} ruleFilter список rule-ids (порожній — усі)
+ * @param {string}   cwd  корінь проєкту
+ * @returns {{ rules: Array<{ ruleId: string, ok: boolean, output: string }> } | { _empty: true } | { _badJson: true }} JSON або маркер помилки
+ */
+function fixCheck(ruleFilter, cwd) {
+  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], { cwd, encoding: 'utf8', timeout: 120_000 })
+  const raw = r.stdout?.trim()
+  if (!raw) return { _empty: true, stderr: r.stderr }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    return { _badJson: true }
+  }
+}
+
+/**
+ * Застосовує T0-auto до кожного провального правила, розділяючи на applied/skipped.
+ * @param {Array<{ ruleId: string, output: string }>} failed провальні правила
+ * @param {string} cwd корінь проєкту
+ * @returns {{ applied: Array<{ ruleId: string, actions: string[] }>, skipped: string[] }} застосовані й пропущені
+ */
+function applyT0ToFailed(failed, cwd) {
+  const applied = []
+  const skipped = []
+  for (const r of failed) {
+    const result = applyT0Auto(r.ruleId, r.output, cwd)
+    if (result.applied) {
+      applied.push({ ruleId: r.ruleId, actions: result.actions })
+    } else {
+      skipped.push(r.ruleId)
+    }
+  }
+  return { applied, skipped }
+}
+
 /**
  * CLI підкоманда `n-cursor fix-t0 [rule...]`.
  * Запускає `fix --json`, застосовує T0-auto для кожного violation,
@@ -126,22 +163,13 @@ export function runT0AutoCli(args, cwd) {
   const verbose = args.includes('--verbose') || args.includes('-v')
 
   // 1. Запустити fix --json
-  const fixResult = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
-    cwd,
-    encoding: 'utf8',
-    timeout: 120_000
-  })
-  const raw = fixResult.stdout?.trim()
-  if (!raw) {
+  const fixJson = fixCheck(ruleFilter, cwd)
+  if (fixJson._empty) {
     console.error(`n-cursor fix-t0: fix --json повернув порожній stdout`)
-    console.error(fixResult.stderr?.slice(0, 300) ?? '')
+    console.error(fixJson.stderr?.slice(0, 300) ?? '')
     return 1
   }
-
-  let fixJson
-  try {
-    fixJson = JSON.parse(raw)
-  } catch {
+  if (fixJson._badJson) {
     console.error(`n-cursor fix-t0: fix --json повернув невалідний JSON`)
     return 1
   }
@@ -153,16 +181,7 @@ export function runT0AutoCli(args, cwd) {
   }
 
   // 2. Застосувати T0-auto
-  const applied = []
-  const skipped = []
-  for (const r of failed) {
-    const result = applyT0Auto(r.ruleId, r.output, cwd)
-    if (result.applied) {
-      applied.push({ ruleId: r.ruleId, actions: result.actions })
-    } else {
-      skipped.push(r.ruleId)
-    }
-  }
+  const { applied, skipped } = applyT0ToFailed(failed, cwd)
 
   if (applied.length === 0) {
     console.log(`⏭️  fix-t0: T0-auto паттерн не підходить для: ${failed.map(r => r.ruleId).join(', ')}`)
@@ -176,18 +195,11 @@ export function runT0AutoCli(args, cwd) {
   }
 
   // 4. Check-gate: перевірити лише ті правила, що ми чіпали
-  const recheck = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...applied.map(a => a.ruleId)], {
-    cwd,
-    encoding: 'utf8',
-    timeout: 120_000
-  })
-  const recheckRaw = recheck.stdout?.trim()
-  if (!recheckRaw) {
+  const recheckJson = fixCheck(applied.map(a => a.ruleId), cwd)
+  if (recheckJson._empty) {
     console.error(`fix-t0: check-gate: fix --json повернув порожній stdout`)
     return 1
   }
-
-  const recheckJson = JSON.parse(recheckRaw)
   const stillFailed = recheckJson.rules.filter(r => !r.ok)
 
   if (verbose) {

package/skills/start-check/js/check.mjs

@@ -111,7 +111,7 @@ function diffSideEffects(before, after) {
  * Запускає `start` одного воркспейсу з grace-таймаутом і класифікує результат.
  * @param {string} cwd корінь репозиторію
  * @param {string} workspace відносний шлях воркспейсу
- * @param {{graceMs?:number, type?:('server'|'cli'), spawnImpl?:Function}} [opts] grace-період, тип (інакше з package.json), інʼєкція spawn для тестів
+ * @param {{graceMs?:number, type?:('server'|'cli'), spawnImpl?:typeof import('node:child_process').spawnSync}} [opts] grace-період, тип (інакше з package.json), інʼєкція spawn для тестів
  * @returns {Promise<{workspace:string, type:string, exitCode:number|null, timedOut:boolean, status:('OK'|'FAIL'), ready:boolean, firstError:string|null, logTail:string, sideEffects:{newFiles:string[], changedTracked:string[]}}>} результат прогону
  */
 export async function runWorkspaceStart(cwd, workspace, opts = {}) {