@nitra/cursor 3.26.0 → 3.27.0

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

@@ -4,14 +4,25 @@
  * Інверсія керування: веде цей JS, а локальна модель — лише сервіс перефразування.
  *   Stage 0  extractFacts        — факти з коду (0 токенів)
  *   Stage 1  sectionInstructions — точкові промпти на кожну секцію (спільний KV-cached префікс)
+ *   Stage 2  stripSignatures     — детермінований зріз сигнатур (0 токенів)
+ *   Stage 2.5 scoreDoc           — детермінований скоринг проти фактів (0 токенів)
  *   Stage 3  assemble            — фіксовані заголовки/порядок + зрізання fence
- * Режим `--oneshot` — база для порівняння (один промпт на весь документ).
+ *   Tier 2   claudeOneShot       — хмарний fallback якщо score < QUALITY_THRESHOLD
+ *
+ * Hybrid routing (sym-threshold):
+ *   sym < BORDERLINE_SYM_LOW          → Tier 1 local (без хмарного рефері)
+ *   sym ∈ [BORDERLINE_SYM_LOW, sym<4) → Tier 1 + cloudScoreDoc (Haiku) → при низькому балі → Tier 2
+ *   sym >= DEFAULT_SYM_THRESHOLD      → одразу Tier 2 (pre-routing, без local)
  */
 import { readFileSync } from 'node:fs'
 import { basename } from 'node:path'
 import { request } from 'node:http'
+import { env } from 'node:process'
+import Anthropic from '@anthropic-ai/sdk'
 import { extractFacts } from './docgen-extract.mjs'
-import { sectionMessages, oneShotMessages } from './docgen-prompts.mjs'
+import { sectionMessages, oneShotMessages, STYLE, oneShotPromptText } from './docgen-prompts.mjs'
+
+const QUALITY_THRESHOLD = 70
 
 /** Один виклик чату до ollama зі streaming (токени стримуються → socket активний, жодного timeout). */
 async function ollamaChat(messages, { model, numPredict = 600 }) {
@@ -70,6 +81,116 @@ function stripSignatures(text) {
   return t
 }
 
+/** Розбиває md на секції за ## заголовками → { огляд, поведінка, api, гарантіїповедінки, … } */
+function parseSections(md) {
+  const result = {}
+  let cur = null
+  for (const line of md.split('\n')) {
+    const m = line.match(/^##\s+(.+)/)
+    if (m) { cur = m[1].toLowerCase().replace(/[^а-яіїєґa-z0-9]/gi, ''); result[cur] = '' }
+    else if (cur) result[cur] += line + '\n'
+  }
+  return result
+}
+
+/**
+ * Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
+ * @returns {{ score: number, issues: string[] }}
+ */
+function scoreDoc(md, facts) {
+  const s = parseSections(md)
+  let score = 100
+  const issues = []
+
+  if (!s['огляд'])
+    { score -= 25; issues.push('no-overview') }
+
+  const behavior = s['поведінка'] ?? ''
+  if (behavior.length < 60)
+    { score -= 20; issues.push('short-behavior') }
+
+  const guarantees = s['гарантіїповедінки'] ?? ''
+  // Будь-яка згадка "кеш" у Гарантіях коли файл не кешує — галюцинація
+  // Негація: "не кешує", "не має кешування", "без кешування", "немає кешу"
+  const cacheHit = /кеш/i.test(guarantees) && !/(?:не|без)\s+(?:\S+\s+)?кеш|немає\s+кеш/i.test(guarantees)
+  if (!facts.markers?.caches && cacheHit)
+    { score -= 20; issues.push('cache-hallucination') }
+
+  // Перевіряємо лише бектік-обгорнуті імена (`sym`) — уникаємо substring false positives
+  const hasName = (text, sym) => text.includes('`' + sym + '`')
+  for (const sym of facts.internalSymbols ?? []) {
+    const inDoc = hasName(guarantees, sym) || hasName(s['огляд'] ?? '', sym) || hasName(s['поведінка'] ?? '', sym)
+    if (inDoc) { score -= 10; issues.push(`internal-name:${sym}`) }
+  }
+
+  return { score: Math.max(0, score), issues }
+}
+
+const SCORE_RUBRIC = `Оціни якість документації для JavaScript-модуля за 4 критеріями (1-3 кожен):
+
+- огляд: 3=описує роль модуля в системі (ЩО і НАВІЩО); 2=частково розмитий; 1=відсутній або перераховує функції
+- поведінка: 3=бізнес-терміни, без деталей реалізації; 2=деякі impl-деталі; 1=переважно реалізація або відсутня
+- гарантії: 3=лише реальні інваріанти підтверджені кодом, без галюцинацій; 2=частково правильні; 1=вигадані або відсутні
+- стиль: 3=без сигнатур/internal-імен, правильна markdown-структура; 2=дрібні порушення; 1=сигнатури/internal-імена/відсутні заголовки
+
+Відповідай ТІЛЬКИ JSON без пояснень:
+{"огляд":N,"поведінка":N,"гарантії":N,"стиль":N,"issues":["коротко про кожен мінус 1-5 слів"]}`
+
+/**
+ * Stage 2.5 cloud: Claude Haiku оцінює якість доку проти коду + фактів.
+ * Використовує найдешевшу хмарну модель — haiku — для мінімальної вартості судді.
+ * @returns {{ score: number, scores: object, issues: string[], tok: number }}
+ */
+async function cloudScoreDoc(md, facts, src, model = 'claude-haiku-4-5-20251001') {
+  const client = new Anthropic()
+  const factsTxt = [
+    facts.exports?.length ? `Публічні функції: ${facts.exports.map(e => e.name).join(', ')}` : '',
+    facts.internalSymbols?.length ? `Внутрішні (не публічні): ${facts.internalSymbols.join(', ')}` : '',
+    facts.markers?.caches ? 'Кешування: є' : 'Кешування: немає',
+    facts.markers?.network ? 'Мережа: є' : 'Мережа: немає',
+    facts.markers?.readOnly ? 'Read-only (не змінює файли/стан)' : ''
+  ].filter(Boolean).join('\n')
+
+  const msg = await client.messages.create({
+    model,
+    max_tokens: 256,
+    system: SCORE_RUBRIC,
+    messages: [{
+      role: 'user',
+      content: [
+        { type: 'text', text: `ФАКТИ:\n${factsTxt}`, cache_control: { type: 'ephemeral' } },
+        { type: 'text', text: `КОД:\n\`\`\`\n${src.slice(0, 4000)}\n\`\`\``, cache_control: { type: 'ephemeral' } },
+        { type: 'text', text: `ДОКУМЕНТАЦІЯ:\n${md}` }
+      ]
+    }]
+  })
+  const tok = (msg.usage?.input_tokens ?? 0) + (msg.usage?.output_tokens ?? 0)
+  try {
+    const j = JSON.parse(msg.content[0]?.text ?? '{}')
+    const total = ((j.огляд ?? 0) + (j.поведінка ?? 0) + (j.гарантії ?? 0) + (j.стиль ?? 0)) / 12 * 100
+    return { score: Math.round(total), scores: j, issues: j.issues ?? [], tok }
+  } catch {
+    return { score: 50, scores: {}, issues: ['parse-error'], tok }
+  }
+}
+
+/** Tier 2: хмарний fallback через Claude коли local-score < QUALITY_THRESHOLD. */
+async function claudeOneShot(facts, src, model = 'claude-sonnet-4-6') {
+  const client = new Anthropic()
+  const prompt = oneShotPromptText(facts, src)
+  const msg = await client.messages.create({
+    model,
+    max_tokens: 1500,
+    system: STYLE,
+    messages: [{ role: 'user', content: prompt }]
+  })
+  const text = msg.content[0]?.text ?? ''
+  const genTok = msg.usage?.output_tokens ?? 0
+  let md = stripSignatures(stripSection(text))
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  return { md: md + '\n', genTok }
+}
+
 /** Stage 3: фіксовані заголовки у фіксованому порядку. */
 function assemble(stem, sections) {
   const order = [
@@ -106,28 +227,108 @@ async function generateOneShot(facts, src, model) {
   return { md: md + '\n', genTok }
 }
 
-/** Головний API: файл → { md, genTok, ms }. */
-export async function generateDoc(file, { model = 'gemma3:4b', mode = 'orchestrated' } = {}) {
+/** Файли з sym ≥ цього значення одразу йдуть у Tier 2 (без локального проходу). */
+const DEFAULT_SYM_THRESHOLD = 4
+/** Файли з sym ≥ цього значення отримують хмарного рефері (Haiku) після локального проходу. */
+const BORDERLINE_SYM_LOW = 2
+
+/**
+ * Головний API: файл → { md, genTok, ms, score, issues, tier }.
+ *
+ * Routing (sym-threshold):
+ *   sym < BORDERLINE_SYM_LOW                   → Tier 1 (без хмарного рефері)
+ *   sym ∈ [BORDERLINE_SYM_LOW, symThreshold)   → Tier 1 + cloudScoreDoc (Haiku) як рефері
+ *   sym >= symThreshold                         → Pre-routing одразу Tier 2
+ *   scoreCloud=true                             → примусово запускає cloudScoreDoc для всіх Tier 1
+ *
+ * @param {string}  scoreModel    — модель для хмарного рефері (Haiku за замовч.)
+ * @param {string}  cloudModel    — модель для Tier 2 генерації (Sonnet за замовч.)
+ * @param {boolean} scoreCloud    — якщо true, cloudScoreDoc запускається для всіх Tier 1 файлів
+ */
+export async function generateDoc(file, {
+  model = 'gemma3:4b',
+  mode = 'orchestrated',
+  scoreModel = 'claude-haiku-4-5-20251001',
+  cloudModel = 'claude-sonnet-4-6',
+  threshold = QUALITY_THRESHOLD,
+  scoreCloud = false,
+  symThreshold = DEFAULT_SYM_THRESHOLD
+} = {}) {
   const src = readFileSync(file, 'utf8')
   const facts = extractFacts(src, file)
   const t0 = Date.now()
-  const r = facts.unsupported
-    ? await generateOneShot(facts, src, model) // fallback для не-JS
+
+  // Pre-routing: складні файли (sym ≥ symThreshold) → одразу Tier 2, не витрачаємо local-час
+  const complexity = facts.internalSymbols?.length ?? 0
+  if (complexity >= symThreshold && env.ANTHROPIC_API_KEY) {
+    const r2 = await claudeOneShot(facts, src, cloudModel)
+    return { ...r2, ms: Date.now() - t0, score: null, issues: [`pre-routed:sym=${complexity}`], tier: 2 }
+  }
+
+  let r = facts.unsupported
+    ? await generateOneShot(facts, src, model)
     : mode === 'oneshot'
       ? await generateOneShot(facts, src, model)
       : await generateOrchestrated(facts, src, model)
-  return { ...r, ms: Date.now() - t0 }
+
+  // Stage 2.5a: детермінований скоринг (0 токенів)
+  const { score: detScore, issues: detIssues } = scoreDoc(r.md, facts)
+
+  // Stage 2.5b: cloudScoreDoc (Haiku) як рефері для borderline-файлів або при scoreCloud=true
+  const isBorderline = complexity >= BORDERLINE_SYM_LOW && complexity < symThreshold
+  if ((isBorderline || scoreCloud) && env.ANTHROPIC_API_KEY) {
+    const cs = await cloudScoreDoc(r.md, facts, src, scoreModel)
+    if (cs.score < threshold) {
+      const r2 = await claudeOneShot(facts, src, cloudModel)
+      return { ...r2, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
+               issues: cs.issues, detScore, detIssues, tier: 2 }
+    }
+    return { ...r, ms: Date.now() - t0, score: cs.score, cloudScores: cs.scores,
+             issues: cs.issues, detScore, detIssues, tier: 1 }
+  }
+
+  // Детермінований fallback (без хмарного рефері)
+  if (detScore < threshold && env.ANTHROPIC_API_KEY) {
+    const r2 = await claudeOneShot(facts, src, cloudModel)
+    return { ...r2, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 2 }
+  }
+
+  return { ...r, ms: Date.now() - t0, score: detScore, issues: detIssues, tier: 1 }
 }
 
-// CLI: node docgen-gen.mjs <file> [--oneshot] [--model <m>]
+// CLI: node docgen-gen.mjs <file> [--oneshot] [--score-cloud] [--model <m>] [--score-model <m>] [--sym-threshold N] [--tier-only]
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 if (isRunAsCli(import.meta.url)) {
   const args = process.argv.slice(2)
   const file = args.find(a => !a.startsWith('--'))
   const mode = args.includes('--oneshot') ? 'oneshot' : 'orchestrated'
+  const scoreCloud = args.includes('--score-cloud')
+  const tierOnly = args.includes('--tier-only')
   const mi = args.indexOf('--model'); const model = mi >= 0 ? args[mi + 1] : 'gemma3:4b'
-  if (!file) { console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--model <m>]'); process.exit(1) }
-  const r = await generateDoc(file, { model, mode })
-  process.stderr.write(`[${mode}] ${r.ms}ms / ${r.genTok} tok\n`)
+  const smi = args.indexOf('--score-model'); const scoreModel = smi >= 0 ? args[smi + 1] : 'claude-haiku-4-5-20251001'
+  const si = args.indexOf('--sym-threshold'); const symThreshold = si >= 0 ? Number(args[si + 1]) : DEFAULT_SYM_THRESHOLD
+  if (!file) {
+    console.error('Usage: node docgen-gen.mjs <file> [--oneshot] [--score-cloud] [--model <m>] [--score-model <m>] [--sym-threshold N] [--tier-only]')
+    process.exit(1)
+  }
+  if (tierOnly) {
+    const src = readFileSync(file, 'utf8')
+    const facts = extractFacts(src, file)
+    const sym = facts.internalSymbols?.length ?? 0
+    let label, icon
+    if (sym >= symThreshold) {
+      icon = '☁️ '; label = `Tier 2 cloud   (sym=${sym} ≥ ${symThreshold}, pre-routed)`
+    } else if (sym >= BORDERLINE_SYM_LOW) {
+      icon = '🔀'; label = `Tier 1+judge   (sym=${sym} ∈ [${BORDERLINE_SYM_LOW},${symThreshold}), Haiku рефері)`
+    } else {
+      icon = '💻'; label = `Tier 1 local   (sym=${sym} < ${BORDERLINE_SYM_LOW})`
+    }
+    process.stdout.write(`${icon} ${label}  |  ${file}\n`)
+    process.exit(0)
+  }
+  const r = await generateDoc(file, { model, mode, scoreCloud, scoreModel, symThreshold })
+  const issuesTxt = r.issues?.length ? ` issues=${r.issues.join(',')}` : ''
+  const cloudTxt = r.cloudScores ? ` cloud-scores=${JSON.stringify(r.cloudScores)}` : ''
+  process.stderr.write(`[tier${r.tier} ${mode}] ${r.ms}ms / ${r.genTok} tok / score=${r.score}${issuesTxt}${cloudTxt}\n`)
   process.stdout.write(r.md)
 }

package/skills/docgen/js/docgen-ignore.mjs

@@ -20,7 +20,9 @@ export const DOCGEN_IGNORE_GLOBS = Object.freeze([
   '.worktrees/**',
   '**/benchmarks/**',
   '**/demo/**',
-  '**/docs/**'
+  '**/docs/**',
+  'npm/reports/**',
+  'npm/bin/**'
 ])
 
 const IGNORE_MATCHERS = DOCGEN_IGNORE_GLOBS.map(glob => picomatch(glob, { dot: true }))

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

@@ -6,7 +6,7 @@
  * оплачується один раз (а не на кожну секцію), і оркестрація перестає програвати в часі.
  */
 
-const STYLE = [
+export const STYLE = [
   'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
   'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
   'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
@@ -80,3 +80,9 @@ export function oneShotMessages(facts, src) {
   return msgs(STYLE,
     `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``)
 }
+
+/** Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK). */
+export function oneShotPromptText(facts, src) {
+  const multi = (facts.exports?.length || 0) > 1
+  return `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
+}

package/skills/fix/SKILL.md

@@ -8,42 +8,16 @@ description: >-
 
 ## Scope
 
-Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`). Не запускай `bun run lint` із цього скілу і не намагайся виправляти його порушення тут — це задача `/n-lint`. Якщо `npx @nitra/cursor fix` чистий, а `bun run lint` лишився червоним — запусти `/n-lint` окремо.
+Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`).
 
 ## Workflow
 
-1. **Діагностика** — запусти перевірку через retry-обгортку `n_cursor_npx` (визначена у worktree-preflight, крок 0.1: переживає транзитну CDN-гонку щойно опублікованої версії, а реальний `❌` від `fix` віддає одразу). Прапорець `--json` дає **структурований** результат у stdout, щоб не парсити термінальний текст. За замовчуванням — лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `n_cursor_npx fix bun ga --json`:
-
-```bash
-n_cursor_npx fix --json
-```
-
-2. **Аналіз** — розбери JSON `{ total, failed, rules: [{ ruleId, ok, output }] }`. Працюй **лише** з елементами `ok:false`; їх `output` містить готові `❌`-повідомлення правила (не парси stdout вручну, не визначай правила з тексту). Якщо `failed === 0` — нічого виправляти.
-
-3. **Виправлення** — для кожного `❌` відкрий відповідне правило з `.cursor/rules/` і виправ:
-   - Створи відсутні конфігураційні файли (`.cspell.json`, `.oxfmtrc.json`, `eslint.config.js`, тощо)
-   - Додай відсутні залежності до `package.json`
-   - Створи або оновити `.vscode/settings.json` та `extensions.json`
-   - Створи відсутні GitHub Actions workflows у `.github/workflows/`
-   - Видали заборонені файли та залежності (`package-lock.json`, `yarn.lock`, prettier, тощо)
-   - Оновити скрипти в `package.json`
-
-4. **Встановлення** — якщо були змінені залежності:
-
 ```bash
-bun i
+n_cursor_npx fix
 ```
 
-5. **Форматування** — відформатуй змінені файли:
+Exit 0 = чисто, 1 = є unresolved (перевір вивід — буде список правил що не закрились після 3 ітерацій).
 
-```bash
-oxfmt .
-```
-
-6. **Верифікація** — перевір що все виправлено (та сама retry-обгортка `n_cursor_npx`); чекаєш `failed === 0`:
-
-```bash
-n_cursor_npx fix --json
-```
+Якщо змінились залежності — `bun i`. Якщо змінились JS/TS файли — `oxfmt .`.
 
-7. **Результат** — `failed` має стати `0` (усі правила `ok:true`). Якщо лишились `ok:false` — повтори кроки 3-6. Лінт-помилки від `bun run lint` тут **не виправляй** — вони на скіл `/n-lint`.
+Для конкретних правил: `n_cursor_npx fix bun ga`.

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

@@ -0,0 +1,181 @@
+/**
+ * LLM-worker для n-fix оркестратора — C1 pattern:
+ *   script збирає контекст (rule .mdc + файли з violation) →
+ *   pi повертає JSON зі змінами →
+ *   script застосовує.
+ *
+ * Всі LLM-виклики через `pi` (користувач налаштовує ключі самостійно).
+ * Tool-use не використовується — LLM отримує повний контекст у промпті.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+export const MODEL_HAIKU = 'claude-haiku-4-5-20251001'
+export const MODEL_SONNET = 'claude-sonnet-4-6'
+
+/**
+ * Витягує відносні шляхи файлів із violation output.
+ * Шукає патерни типу `path/to/file.ext` або `[ws] path/to/file.ext:123`.
+ *
+ * @param {string} output violation output з fix check
+ * @returns {string[]} унікальні відносні шляхи
+ */
+function extractFilePaths(output) {
+  const seen = new Set()
+  const results = []
+  // Матчить шляхи: слово/крапка/тире, з розширенням, необов'язковий :рядок на кінці
+  const re = /(?:^|\s|\[[\w/]+\]\s)([\w./][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  for (const m of output.matchAll(re)) {
+    const p = m[1]
+    if (!seen.has(p)) { seen.add(p); results.push(p) }
+  }
+  return results
+}
+
+/**
+ * Будує prompt для pi: правило + порушення + поточний вміст файлів.
+ *
+ * @param {string} ruleId
+ * @param {string} ruleMdc   вміст .mdc-файлу правила
+ * @param {string} output    violation output
+ * @param {Array<{path:string, content:string}>} files
+ * @returns {string}
+ */
+function buildPrompt(ruleId, ruleMdc, output, files) {
+  const filesBlock = files.length === 0
+    ? '(no files identified)'
+    : files.map(f => `<file path="${f.path}">\n${f.content}\n</file>`).join('\n\n')
+
+  return [
+    `You fix project structure violations. Return ONLY valid JSON — no explanation, no markdown.`,
+    ``,
+    `Rule (n-${ruleId}.mdc):`,
+    `---`,
+    ruleMdc,
+    `---`,
+    ``,
+    `Violation output:`,
+    output,
+    ``,
+    `Current file contents:`,
+    filesBlock,
+    ``,
+    `Return JSON with this exact shape:`,
+    `{"changes":[{"path":"relative/path/to/file","content":"full corrected file content"}]}`,
+    ``,
+    `Rules:`,
+    `- "path" is relative to the project root`,
+    `- "content" is the complete new file content (not a diff)`,
+    `- Only include files that actually need to change`,
+    `- If nothing can be fixed automatically, return {"changes":[],"error":"reason"}`,
+  ].join('\n')
+}
+
+/**
+ * Запускає pi і повертає stdout як рядок.
+ *
+ * @param {string} prompt
+ * @param {string} model
+ * @returns {{ text: string, error?: string }}
+ */
+function callPi(prompt, model) {
+  const r = spawnSync(
+    'pi',
+    ['-p', prompt, '--model', model, '--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) ?? ''
+    return { text: '', error: `pi exit ${r.status}: ${stderr}` }
+  }
+  return { text: r.stdout?.trim() ?? '' }
+}
+
+/**
+ * Парсить JSON-відповідь від pi.
+ * pi може обгорнути JSON у ```json ... ```, тому пробуємо витягти.
+ *
+ * @param {string} text
+ * @returns {{ changes: Array<{path:string,content:string}>, error?: string } | null}
+ */
+function parseResponse(text) {
+  // Спроба 1: прямий JSON
+  try { return JSON.parse(text) } catch { /* fallthrough */ }
+
+  // Спроба 2: витягти з ```json ... ```
+  const m = text.match(/```(?:json)?\s*([\s\S]*?)```/)
+  if (m) {
+    try { return JSON.parse(m[1].trim()) } catch { /* fallthrough */ }
+  }
+
+  // Спроба 3: перший { ... } блок
+  const start = text.indexOf('{')
+  const end = text.lastIndexOf('}')
+  if (start !== -1 && end > start) {
+    try { return JSON.parse(text.slice(start, end + 1)) } catch { /* fallthrough */ }
+  }
+
+  return null
+}
+
+/**
+ * LLM-worker: виправляє одне rule-порушення через pi (C1 pattern).
+ *
+ * @param {string} ruleId
+ * @param {string} violationOutput  output з fix check для цього rule
+ * @param {string} projectRoot      абсолютний шлях до кореня проєкту
+ * @param {{ model?: string }} opts
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
+  const model = opts.model ?? MODEL_HAIKU
+
+  // 1. Читаємо rule .mdc
+  const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
+  const ruleMdc = existsSync(mdcPath) ? readFileSync(mdcPath, 'utf8') : '(rule file not found)'
+
+  // 2. Витягуємо файли з violation output і читаємо їх
+  const filePaths = extractFilePaths(violationOutput)
+  const files = filePaths
+    .map(p => {
+      const abs = join(projectRoot, p)
+      if (!existsSync(abs)) return null
+      try {
+        return { path: p, content: readFileSync(abs, 'utf8') }
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+
+  // 3. Будуємо prompt і викликаємо pi
+  const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files)
+  const { text, error: piError } = callPi(prompt, model)
+
+  if (piError) return { ok: false, error: piError }
+  if (!text) return { ok: false, error: 'pi returned empty response' }
+
+  // 4. Парсимо відповідь
+  const parsed = parseResponse(text)
+  if (!parsed) return { ok: false, error: `cannot parse pi response: ${text.slice(0, 200)}` }
+  if (parsed.error) return { ok: false, error: parsed.error }
+
+  const changes = parsed.changes ?? []
+  if (changes.length === 0) return { ok: false, error: 'pi returned no changes' }
+
+  // 5. Застосовуємо зміни
+  for (const change of changes) {
+    if (!change.path || typeof change.content !== 'string') continue
+    const abs = join(projectRoot, change.path)
+    try {
+      writeFileSync(abs, change.content, 'utf8')
+    } catch (e) {
+      return { ok: false, error: `write ${change.path}: ${e.message}` }
+    }
+  }
+
+  return { ok: true }
+}

package/skills/fix/js/orchestrator.mjs

@@ -0,0 +1,128 @@
+/**
+ * Автономний оркестратор n-fix: convergence-loop без участі агента-LLM.
+ *
+ * Тири:
+ *   T0      — детерміністична перевірка (runFixCheck, 0 LLM)
+ *   T0-auto — regex-парсинг violation → програмний фікс (0 LLM)
+ *   T1      — LLM через pi (haiku → sonnet ескалація)
+ *   check-gate — re-run T0 після кожного тіру; loop до maxIter
+ *
+ * meta.json: { "orchestrator": true } — CLI маршрутизує `fix` сюди.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const HERE = fileURLToPath(new URL('.', import.meta.url))
+const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
+
+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
+ */
+export async function runOrchestratorCli(args, cwd) {
+  const { runLlmWorker, MODEL_HAIKU, MODEL_SONNET } = await import('./llm-worker.mjs')
+
+  const maxIterIdx = args.indexOf('--max-iter')
+  const maxIter =
+    maxIterIdx !== -1
+      ? Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || 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))
+
+  console.log(`🔄 n-cursor fix`)
+  if (ruleFilter.length) console.log(`   rules: ${ruleFilter.join(', ')}`)
+
+  /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
+  const failCount = new Map()
+
+  for (let iter = 1; iter <= maxIter; iter++) {
+    console.log(`\n── Ітерація ${iter}/${maxIter} ──`)
+
+    // ── T0: check ──
+    const state = runFixCheck(cwd, ruleFilter)
+    if (!state) {
+      console.error(`❌ fix: перевірка повернула помилку`)
+      return 1
+    }
+
+    const failed = state.rules.filter(r => !r.ok)
+    if (failed.length === 0) {
+      console.log(`✅ fix: 0/${state.total} порушень`)
+      return 0
+    }
+
+    console.log(`   ❌ ${failed.length}: ${failed.map(r => r.ruleId).join(', ')}`)
+
+    // ── T0-auto: детермінований фікс без LLM ──
+    spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'inherit' })
+
+    const stateAfterT0 = runFixCheck(cwd, ruleFilter)
+    const failedAfterT0 = stateAfterT0?.rules.filter(r => !r.ok) ?? failed
+    if (failedAfterT0.length === 0) {
+      console.log(`✅ fix: всі правила закриті T0-auto`)
+      return 0
+    }
+
+    // ── T1: LLM через pi ──
+    for (const rule of failedAfterT0) {
+      const prevFails = failCount.get(rule.ruleId) ?? 0
+      const model = prevFails >= ESCALATE_AFTER ? MODEL_SONNET : MODEL_HAIKU
+      const tier = prevFails >= ESCALATE_AFTER ? 'sonnet' : 'haiku'
+
+      console.log(`\n⚡ [${tier}] → ${rule.ruleId}`)
+
+      const result = await runLlmWorker(rule.ruleId, rule.output, cwd, { model })
+
+      if (result.ok) {
+        console.log(`   ✅ закрито`)
+        failCount.delete(rule.ruleId)
+      } else {
+        failCount.set(rule.ruleId, prevFails + 1)
+        console.log(`   ❌ (${prevFails + 1}× fail): ${result.error ?? ''}`)
+      }
+    }
+  }
+
+  // ── Фінальна перевірка ──
+  const final = runFixCheck(cwd, ruleFilter)
+  const finalFailed = final?.rules.filter(r => !r.ok) ?? []
+
+  if (finalFailed.length === 0) {
+    console.log(`\n✅ fix: чисто`)
+    return 0
+  }
+
+  console.log(`\n❌ fix: ${finalFailed.length} unresolved після ${maxIter} ітерацій`)
+  console.log(`   ${finalFailed.map(r => r.ruleId).join(', ')}`)
+  return 1
+}
+
+/**
+ * Внутрішня check-gate: запускає fix-перевірки і повертає структурований результат.
+ * Не є публічним CLI — викликається лише оркестратором.
+ *
+ * @param {string}   cwd
+ * @param {string[]} ruleFilter
+ * @returns {{ total: number, failed: number, rules: Array<{ ruleId: string, ok: boolean, output: string }> } | null}
+ */
+function runFixCheck(cwd, ruleFilter = []) {
+  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000,
+  })
+  const stdout = r.stdout?.trim()
+  if (!stdout) return null
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    return null
+  }
+}