@nitra/cursor 12.15.0 → 12.16.0

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

@@ -3,29 +3,31 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: c34d0630
+  crc: 49146418
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль відповідає за управління процесом вирішення порушень. Він будує послідовність тирів ескалації за допомогою `buildLadder`. Функція `parseOrchestratorArgs` визначає бюджет LLM та фільтр правил. Далі, `runOrchestratorCli` виконує процес виправлення правил, послідовно застосовуючи `escalateRule` по тирах до досягнення першого успішного вирішення.
+## Огляд
+
+Цей модуль керує процесом виправлення порушень. Він виконує функцію `parseOrchestratorArgs` для визначення обсягу роботи з хмарними моделями та фільтрами правил. Модуль забезпечує класифікацію помилок через `classifyFixError` та ескалацію правил за допомогою `escalateRule`. Крім того, він створює структуру для застосування правил за допомогою `buildLadder` і запускає основний клієнтський процес за допомогою `runOrchestratorCli`.
 
 ## Поведінка
 
-buildLadder будує послідовність тирів ескалації для вирішення порушень.
-escalateRule проходить по послідовності тирів, намагаючись вирішити одне правило до першого успішного перевірки.
-parseOrchestratorArgs парсить аргументи командного рядка для визначення максимального бюджету LLM та фільтра правил.
-runOrchestratorCli виконує повний процес виправлення правил, використовуючи послідовність тирів та бюджет LLM.
+Поведінка:
+classifyFixError визначає тип помилки, виниклої при спробі виправлення.
+buildLadder конструює послідовність моделей для багаторівневої спроби усунення порушень.
+escalateRule ітерує по моделях драбини, намагаючись виправити одне порушення, і звітує про результат.
+parseOrchestratorArgs виділяє максимальну кількість викликів хмарної моделі та фільтр правил із вхідних аргументів.
+runOrchestratorCli виконує повний цикл фіксації порушень, включаючи початкову перевірку, детерміноване виправлення та ітерації з LLM.
 
 ## Публічний API
 
-buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів. Недоступні рівні ігноруються.
-
-escalateRule — Виконує один етап перевірки за драбиною ескалації. Для кожного кроку викликається модель, відбувається повторна перевірка правила, і результат фіксується в лозі. Процес може зупинитися достроково при певних умовах або після вичерпання ліміту.
-
-parseOrchestratorArgs — Витягує максимальне значення для середнього бюджету з аргументів командного рядка та збирає список фільтрів правил.
-
-runOrchestratorCli — Запускає основний процес оркестрації, обробляючи аргументи та керуючи виконанням правил.
+classifyFixError — Визначає тип помилки, яку виявив pi-agent-fix: системна, транспортна чи якісна.
+buildLadder — Створює послідовність моделей для усунення помилок, починаючи з найменш ресурсомістких локальних спроб і рухаючись до хмарних моделей, враховуючи попередній досвід.
+escalateRule — Застосовує одне правило за визначеною драбиною, повторюючи перевірку після кожного кроку та фіксуючи результати у лозі.
+parseOrchestratorArgs — Зчитує аргументи командного рядка, зокрема максимальний бюджет середнього рівня, та витягує фільтр правил.
+runOrchestratorCli — Виконує основну логіку оркестрації, керуючи циклом виявлення, класифікації та ескалації виправлень.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/escalation-log.mjs

@@ -5,7 +5,7 @@
  * правило стало зеленим після цього рунга (`recheckOk` = «чи допомогло»),
  * залишковий violation і `diagnosis` (само-аналіз моделі «чому не вдалося»).
  *
- * Це доповнення до always-on wire-trace (`lib/omlx-trace.mjs`): trace знає
+ * Це доповнення до always-on wire-trace (`lib/pi-trace.mjs`): trace знає
  * `messages`/`reasoning`/`usage` кожного виклику, але **не** знає результату
  * re-check — а саме «чи допомогло» й потрібне для пост-аналізу драбини. Join із
  * trace — за полем `caller` (`fix:<rule>:<rung>`), яке цей модуль і формує.

package/scripts/lib/fix/orchestrator.mjs

@@ -4,10 +4,9 @@ import { env } from 'node:process'
 import { runConformanceCheck } from './run-conformance-check.mjs'
 import { runT0AutoCli } from './t0.mjs'
 import { logEscalation } from './escalation-log.mjs'
-import { runLlmWorker } from './llm-worker.mjs'
-import { printVerboseBlock } from './verbose-block.mjs'
-import { classifyOmlxError } from '../../../lib/llm.mjs'
-import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
+import { runPiAgentFix } from '../../../lib/pi-agent-fix.mjs'
+import { recordFixTelemetry } from '../../../lib/pi-telemetry-store.mjs'
+import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/pi-model-tiers.mjs'
 
 /**
  * Дефолтний кеп на виклики хмарної avg-моделі за один прогін (щоб драбина на N
@@ -16,22 +15,41 @@ import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
 const DEFAULT_MAX_AVG = 3
 
 /**
- * Timeout одного LLM-виклику за тиром. Локальні рунги **fail-fast**: не палити
- * стіну 120s на повільному 4b (curl exit 28) — швидше абортнути й ескалувати.
- * Хмарні — повний. Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
+ * Timeout усієї агентної сесії за тиром. Агентний фікс — багатоходовий
+ * (read→edit→self_check, кожен turn = окремий API-раунд), тож на правилах із багатьма
+ * порушеннями навіть швидкий cloud не вкладається у пару хвилин (вимір: gpt-5.4-mini
+ * timeout на test/doc-files/npm-module за 120s). Тому cloud — теж 5 хв, як local;
+ * основний backstop усе одно turn-ceiling (~50) у pi-agent-fix.
+ * Перевизначення: `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`.
  */
-const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
-const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 300_000
+const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 300_000
 
-/** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */
-const NO_KEY_RE = /немає ключа|api key/i
+/** Реальний транспорт-збій провайдера (мережа/сокет) — НЕ наш агентний backstop-timeout. */
+const TRANSPORT_RE = /etimedout|timed out|econnrefused|connection refused/i
 
 /**
- * Хмарний транспорт (pi) упав на рівні процесу: таймаут/spawn-помилка. Стіна часу
- * однакова для всіх cloud-рунгів (та сама pi-транспортна стіна), а cloud-avg — інша
- * модель, не більший timeout. Ескалація на неї лише спалить avg-бюджет → обрив.
+ * Systemic — повтор тієї ж моделі марний: нема git, fail-closed guard, відсутня модель,
+ * registry/session/auth. Quality — модель видала поганий фікс (retry/escalate може допомогти).
  */
-const CLOUD_TRANSPORT_RE = /etimedout|timed out|pi error/i
+const SYSTEMIC_RE = /не git-репо|fail-closed|write-guard|модель не знайдена|registry:|session:|немає ключа|api key/i
+
+/**
+ * Класифікує помилку pi-agent-fix: systemic | transport | quality (замінює
+ * `classifyOmlxError` після pi-міграції — помилки приходять як винятки з `session.prompt`).
+ * @param {string|null|undefined} error повідомлення помилки
+ * @returns {'systemic'|'transport'|'quality'|null} клас
+ */
+export function classifyFixError(error) {
+  if (!error) return null
+  // Наш агентний backstop-timeout — НЕ транспорт-збій провайдера: модель працювала, просто
+  // не встигла. Тому quality (а не transport-break) → драбина падає на наступний (сильніший)
+  // rung, замість обриву; для cloud-min це означає шанс cloud-avg.
+  if (/^fix timeout /i.test(error)) return 'quality'
+  if (SYSTEMIC_RE.test(error)) return 'systemic'
+  if (TRANSPORT_RE.test(error)) return 'transport'
+  return 'quality'
+}
 
 /**
  * Будує драбину ескалації за наявними тирами (спека 2026-06-19-fix-escalation-cascade):
@@ -72,9 +90,9 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
  */
 function decideAfterFailure(rung, error) {
   if (!error) return null
-  if (NO_KEY_RE.test(error)) return 'break'
-  if (rung.local && classifyOmlxError(error) === 'systemic') return 'skip-model'
-  if (!rung.local && CLOUD_TRANSPORT_RE.test(error)) return 'break'
+  const kind = classifyFixError(error)
+  if (kind === 'systemic') return rung.local ? 'skip-model' : 'break'
+  if (!rung.local && kind === 'transport') return 'break'
   return null
 }
 
@@ -87,7 +105,7 @@ function decideAfterFailure(rung, error) {
  * @param {string} cwd корінь проєкту
  * @param {{
  *   ladder: Array<{tier:string,model:string,feedback:boolean,local:boolean,isAvg:boolean}>,
- *   worker: { runLlmWorker: (ruleId: string, violation: string, cwd: string, opts: object) => object },
+ *   worker: { runFix: (ruleId: string, violation: string, cwd: string, opts: object) => Promise<object> },
  *   check: (rules: string[], cwd: string) => Promise<{rules: Array<{ruleId:string,ok:boolean,output:string}>}>,
  *   avgBudget: number,
  *   clock?: () => number,
@@ -125,42 +143,59 @@ export async function escalateRule(rule, cwd, deps) {
     }
 
     const startedAt = clock()
-    const res = worker.runLlmWorker(rule.ruleId, currentViolation, cwd, {
+    // self_check (advisory §4+5) — той самий verdict-helper, що й зовнішній re-check.
+    const selfCheck = async () => {
+      const r = await check([rule.ruleId], cwd)
+      return { ok: r.rules.every(x => x.ok), output: r.rules.find(x => !x.ok)?.output ?? 'ok' }
+    }
+    const res = await worker.runFix(rule.ruleId, currentViolation, cwd, {
       model: rung.model,
+      tier: rung.tier,
       feedback: rung.feedback ? feedback : null,
       caller: `fix:${rule.ruleId}:${rung.tier}`,
-      timeoutMs: rung.timeoutMs
+      timeoutMs: rung.timeoutMs,
+      deps: { selfCheck }
     })
     if (rung.isAvg) avgUsed++
 
+    // Зовнішній canonical re-check = джерело правди (§4+5).
     const recheck = await check([rule.ruleId], cwd)
     const recheckOk = recheck.rules.every(r => r.ok)
     const remaining = recheckOk ? '' : (recheck.rules.find(r => !r.ok)?.output ?? '')
+
+    // Distillation-стор §13: persist кожну спробу (повні edits + verdict).
+    if (res.telemetry) {
+      recordFixTelemetry({
+        ...res.telemetry,
+        violationSignature: currentViolation,
+        recheck: { external: recheckOk ? 'pass' : 'fail' },
+        escalated: !recheckOk
+      })
+    }
+
     record({
       ...common,
-      callOk: res.ok,
+      callOk: !res.error,
       callError: res.error ?? null,
       recheckOk,
       remainingViolation: remaining,
-      diagnosis: res.diagnosis ?? null,
+      diagnosis: res.telemetry ? `turns=${res.telemetry.turnCount} tools=${res.telemetry.toolCallCount}` : null,
       ms: clock() - startedAt
     })
 
     if (recheckOk) {
       log(`  ✅ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}`)
-    } else {
-      const hint = res.error ? ` ❌ ${res.error.slice(0, 120)}` : ' ❌ досі порушено'
-      log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
+      return { resolved: true, avgUsed }
     }
 
-    if (env.N_CURSOR_FIX_VERBOSE !== 'off' && res.promptSummary) {
-      printVerboseBlock(rule.ruleId, res.promptSummary, res.reasoning ?? null, res.reasoningSource ?? null)
-    }
+    const hint = res.error ? ` ❌ ${res.error.slice(0, 120)}` : ' ❌ досі порушено'
+    log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
 
-    if (recheckOk) return { resolved: true, avgUsed }
+    // Recheck провалився → clean-slate per rung: відкотити правки цього рунга (§12).
+    res.rollback?.()
 
     // Feedback для наступного рунга + оновлений violation.
-    feedback = { previousModel: rung.model, previousChanges: res.changes ?? [], previousError: res.error ?? null }
+    feedback = { previousModel: rung.model, previousError: res.error ?? null }
     currentViolation = remaining || currentViolation
 
     const action = decideAfterFailure(rung, res.error)
@@ -210,7 +245,7 @@ async function runT0Step(cwd, ruleFilter, failed) {
  * @returns {Promise<number>}  0 = all clean, 1 = unresolved
  */
 export async function runOrchestratorCli(args, cwd) {
-  const worker = { runLlmWorker }
+  const worker = { runFix: runPiAgentFix }
   const { maxAvg, ruleFilter } = parseOrchestratorArgs(args)
   const ladder = buildLadder({ localMin: LOCAL_MIN, cloudMin: CLOUD_MIN, cloudAvg: CLOUD_AVG })
 

package/scripts/lib/run-lint.mjs

@@ -166,22 +166,14 @@ async function runPerFileRules(ids, ctx) {
 }
 
 /**
- * Конформність-фаза `--full` (поглинула `fix`): escalation-аналітику обрамляє зсувом логу
- * (записи саме цього прогону), у fix-режимі по конформності викликає аналіз.
+ * Конформність-фаза `--full`.
  * @param {string} cwd корінь
  * @param {boolean} readOnly лише детект
  * @param {(s: string) => void} log логер
  * @returns {Promise<number>} код конформності
  */
 async function runFullConformancePhase(cwd, readOnly, log) {
-  const { escalationLogSize, maybeAnalyzeEscalation, reportRunStats } = await import('./fix/analyze-escalation.mjs')
-  const escOffset = readOnly ? 0 : escalationLogSize()
-  const conformanceCode = await runConformance(cwd, readOnly, log)
-  if (!readOnly) {
-    reportRunStats(escOffset, log) // резюме викликів моделей (локальна / cloud-min / cloud-avg)
-    maybeAnalyzeEscalation(cwd, escOffset, log)
-  }
-  return conformanceCode
+  return runConformance(cwd, readOnly, log)
 }
 
 /**

package/scripts/lib/skill-meta.mjs

@@ -19,6 +19,15 @@ import { join } from 'node:path'
 /** Літерал безумовної автоактивації (українською, як у `auto-skills.mjs`). */
 export const SKILL_ALWAYS = 'завжди'
 
+/** Допустимі тири моделі для агентного виконання скіла (`pi`-runner). */
+export const SKILL_TIERS = ['min', 'avg', 'max']
+
+/**
+ * Дефолтна тира за відсутності `main.json.tier`: скіли відкриті й агентні, слабка
+ * локальна модель іде в мета-рамблінг, тож безпечніше дефолтити в найсильніший тир.
+ */
+export const DEFAULT_SKILL_TIER = 'max'
+
 /**
  * @typedef {{ always: true } | { rules: string[] }} SkillAutoSpec
  */
@@ -50,6 +59,19 @@ export function skillRequiresRoot(meta) {
   return meta?.worktree === true || meta?.requireRoot === true
 }
 
+/**
+ * Тира моделі для агентного виконання скіла (`pi`-runner). Повертає `main.json.tier`,
+ * якщо це валідний тир, інакше — `DEFAULT_SKILL_TIER` (`max`).
+ * @param {Record<string, unknown> | null} meta розпарсений `main.json` (або null)
+ * @returns {'min'|'avg'|'max'} тира
+ */
+export function skillTier(meta) {
+  const tier = meta?.tier
+  return typeof tier === 'string' && SKILL_TIERS.includes(tier)
+    ? /** @type {'min'|'avg'|'max'} */ (tier)
+    : DEFAULT_SKILL_TIER
+}
+
 /**
  * Читає й парсить `main.json` одного скіла.
  * @param {string} skillDir абсолютний шлях до каталогу скіла

package/scripts/skills-cli.mjs

@@ -3,14 +3,16 @@
  *
  * Скіли читаються з `npm/skills/<id>/SKILL.md` установленого пакета (або кешу `npx`).
  * Промпт збирає інструкцію скілу + контекст поточного CWD (`package.json`, `tsconfig.json`,
- * `.n-cursor.json`) — далі stdout або делегування в `cursor-agent` / `claude`.
+ * `.n-cursor.json`) — далі stdout або виконання через вбудований pi-агент
+ * (рекомендовано), чи deprecated-делегування в `cursor-agent` / `claude`.
  *
  * Підтримувані формати:
  *   `npx \@nitra/cursor skill list`
  *   `npx \@nitra/cursor skill taze`
- *   `npx \@nitra/cursor skill cursor taze`
- *   `npx \@nitra/cursor skill cursor taze "онови залежності"`
- *   `npx \@nitra/cursor skill claude taze` — те саме через Claude Code CLI
+ *   `npx \@nitra/cursor skill pi taze` — виконати через вбудований pi-агент (рекомендовано)
+ *   `npx \@nitra/cursor skill pi taze "онови залежності"`
+ *   `npx \@nitra/cursor skill cursor taze` — deprecated: зовнішній Cursor CLI
+ *   `npx \@nitra/cursor skill claude taze` — deprecated: зовнішній Claude Code CLI
  */
 
 import { spawnSync } from 'node:child_process'
@@ -19,14 +21,18 @@ import { dirname, join } from 'node:path'
 import { cwd } from 'node:process'
 import { fileURLToPath } from 'node:url'
 
-const RUNNERS = new Set(['cursor', 'claude'])
+import { readSkillMetaRaw, skillTier } from './lib/skill-meta.mjs'
+
+/** Виконавці скіла. `pi` — вбудований (рекомендований); `cursor`/`claude` — deprecated зовнішні CLI. */
+const RUNNERS = new Set(['pi', 'cursor', 'claude'])
 
 const USAGE_LINES = [
   'Usage:',
   '  npx @nitra/cursor skill list',
   '  npx @nitra/cursor skill <skill-id> ["task"]',
-  '  npx @nitra/cursor skill cursor <skill-id> ["task"]',
-  '  npx @nitra/cursor skill claude <skill-id> ["task"]',
+  '  npx @nitra/cursor skill pi <skill-id> ["task"]      # вбудований pi-агент (рекомендовано)',
+  '  npx @nitra/cursor skill cursor <skill-id> ["task"]  # deprecated',
+  '  npx @nitra/cursor skill claude <skill-id> ["task"]  # deprecated',
   '',
   'Skill id: каталог у пакеті (lint, taze, …) або з префіксом n- (n-lint → lint).'
 ]
@@ -124,15 +130,43 @@ export function buildSkillPrompt(skillsRoot, rawSkillName, task, projectDir = cw
 }
 
 /**
+ * Виконує скіл через вбудований pi-агент (рекомендований шлях). Модель — з тиру скіла
+ * (`main.json.tier`, дефолт `max`); `cwd` = каталог виклику (worktree, за потреби,
+ * створює сам скіл за SKILL.md-preflight). Pi вантажиться lazy.
+ * @param {string} prompt готовий `buildSkillPrompt`
+ * @param {string} rawSkillName ім'я скілу з CLI (можливо з префіксом n-)
+ * @param {string} skillsRoot абсолютний шлях до `skills/` пакета
+ * @param {string} projectDir робочий каталог сесії (= каталог виклику)
+ * @param {(line: string) => void} logError вивід помилок
+ * @param {{ runPiAgentSkill?: Function }} deps інжекти для тестів
+ * @returns {Promise<number>} exit code (0 — ok)
+ */
+async function runPiRunner(prompt, rawSkillName, skillsRoot, projectDir, logError, deps = {}) {
+  const skillId = normalizeSkillId(rawSkillName)
+  const tier = skillTier(readSkillMetaRaw(join(skillsRoot, skillId)))
+  const runPiAgentSkill = deps.runPiAgentSkill ?? (await import('../lib/pi-agent-skill.mjs')).runPiAgentSkill
+  const result = await runPiAgentSkill(prompt, { skillId, tier, cwd: projectDir })
+  if (result.error) {
+    logError(result.error)
+  }
+  return result.ok ? 0 : 1
+}
+
+/**
+ * Deprecated: делегує у зовнішній `claude -p` / `cursor-agent -p`. Лишається як fallback
+ * для тих, у кого pi-модель ще не налаштована; буде прибрано (мігруй на `skill pi`).
  * @param {'claude' | 'cursor'} kind який LLM CLI запускати
  * @param {string} prompt промпт для передачі у stdin
  * @param {string} projectDir робочий каталог дочірнього процесу
+ * @param {(line: string) => void} logError вивід попередження/помилок
  * @returns {number} exit code дочірнього процесу
  */
-function runLlmCli(kind, prompt, projectDir) {
+function runLlmCli(kind, prompt, projectDir, logError) {
+  logError(`[deprecated] skill ${kind} → use 'skill pi'; зовнішній CLI буде прибрано`)
+
   if (kind === 'claude') {
     if (!isBinaryInPath('claude')) {
-      throw new Error('`claude` not found in PATH. Install Claude Code CLI or use `skill cursor`.')
+      throw new Error('`claude` not found in PATH. Install Claude Code CLI or use `skill pi`.')
     }
 
     const result = spawnSync('claude', ['-p'], {
@@ -145,7 +179,7 @@ function runLlmCli(kind, prompt, projectDir) {
   }
 
   if (!isBinaryInPath('cursor-agent')) {
-    throw new Error('`cursor-agent` not found in PATH. Install Cursor CLI or use `skill claude`.')
+    throw new Error('`cursor-agent` not found in PATH. Install Cursor CLI or use `skill pi`.')
   }
 
   const result = spawnSync('cursor-agent', ['-p'], {
@@ -168,15 +202,16 @@ export function resolveBundledPackageRoot(fromModuleUrl = import.meta.url) {
 
 /**
  * @param {string[]} argv аргументи після `skill` у `n-cursor`
- * @param {{ packageRoot?: string, projectDir?: string, log?: (line: string) => void, logError?: (line: string) => void }} [options] перевизначення кореня пакета, каталогу проєкту та функцій виводу (для тестів)
- * @returns {number} exit code
+ * @param {{ packageRoot?: string, projectDir?: string, log?: (line: string) => void, logError?: (line: string) => void, deps?: { runPiAgentSkill?: Function } }} [options] перевизначення кореня пакета, каталогу проєкту, функцій виводу та інжектів (для тестів)
+ * @returns {Promise<number>} exit code
  */
-export function runSkillsCli(argv, options = {}) {
+export async function runSkillsCli(argv, options = {}) {
   const log = options.log ?? (line => console.log(line))
   const logError = options.logError ?? (line => console.error(line))
   const packageRoot = options.packageRoot ?? resolveBundledPackageRoot()
   const skillsRoot = join(packageRoot, 'skills')
   const projectDir = options.projectDir ?? cwd()
+  const deps = options.deps ?? {}
 
   const [first, second, ...rest] = argv
   const skillIds = listSkillIds(skillsRoot)
@@ -201,7 +236,10 @@ export function runSkillsCli(argv, options = {}) {
       }
       const task = rest.join(' ')
       const prompt = buildSkillPrompt(skillsRoot, second, task, projectDir)
-      return runLlmCli(/** @type {'claude' | 'cursor'} */ (first), prompt, projectDir)
+      if (first === 'pi') {
+        return await runPiRunner(prompt, second, skillsRoot, projectDir, logError, deps)
+      }
+      return runLlmCli(/** @type {'claude' | 'cursor'} */ (first), prompt, projectDir, logError)
     }
 
     if (skillIds.includes(normalizeSkillId(first))) {

package/scripts/utils/ast-extract.mjs

@@ -0,0 +1,105 @@
+/** @see ./docs/ast-extract.md */
+
+/**
+ * Generic AST-facts extractor для `ast_facts`-tool fix-engine (§3б спеки pi-migration).
+ *
+ * Дає агенту структурований зріз файлу (`imports` / `exports` / `topLevelFunctions`)
+ * замість сирого вмісту — скорочує redundant read-turns на слабкій локальній моделі.
+ * Використовується як **generic fallback**, коли правило не має власного
+ * `rules/<id>/js/_ast-context.mjs`.
+ *
+ * Парсинг — через спільний `parseProgramOrNull` (oxc). Будь-яка помилка (read/parse)
+ * деградує до `{ error, imports:[], exports:[], topLevelFunctions:[] }`, щоб агент
+ * продовжив із тим, що має (контракт §3б: fallback до голого вмісту).
+ */
+
+import { readFileSync } from 'node:fs'
+import { parseProgramOrNull } from './ast-scan-utils.mjs'
+
+/** Порожній результат із причиною (read/parse fail). @param {string} error причина */
+function empty(error) {
+  return { error, imports: [], exports: [], topLevelFunctions: [] }
+}
+
+/** Чи init-вираз — функція (для `export const f = () => …`). @param {unknown} node init */
+function isFunctionInit(node) {
+  return !!node && (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression')
+}
+
+/**
+ * Витягає AST-факти з вихідного коду (без файлового IO — для тестів і reuse).
+ * @param {string} content вихідний код
+ * @param {string} virtualPath шлях (визначає мову js/ts/jsx/tsx)
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContextFromSource(content, virtualPath) {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return empty('parse failed')
+
+  const imports = []
+  const exports = []
+  const topLevelFunctions = []
+
+  for (const node of program.body ?? []) {
+    switch (node?.type) {
+      case 'ImportDeclaration':
+        imports.push({
+          source: node.source?.value ?? '',
+          names: (node.specifiers ?? []).map(s => s.local?.name).filter(Boolean)
+        })
+        break
+
+      case 'FunctionDeclaration':
+        if (node.id?.name) topLevelFunctions.push(node.id.name)
+        break
+
+      case 'ExportNamedDeclaration': {
+        const d = node.declaration
+        if (d?.type === 'FunctionDeclaration' && d.id?.name) {
+          exports.push(d.id.name)
+          topLevelFunctions.push(d.id.name)
+        } else if ((d?.type === 'ClassDeclaration' || d?.type === 'TSInterfaceDeclaration') && d.id?.name) {
+          exports.push(d.id.name)
+        } else if (d?.type === 'VariableDeclaration') {
+          for (const decl of d.declarations ?? []) {
+            if (!decl.id?.name) continue
+            exports.push(decl.id.name)
+            if (isFunctionInit(decl.init)) topLevelFunctions.push(decl.id.name)
+          }
+        }
+        for (const spec of node.specifiers ?? []) {
+          if (spec.exported?.name) exports.push(spec.exported.name)
+        }
+        break
+      }
+
+      case 'ExportDefaultDeclaration':
+        exports.push('default')
+        break
+
+      case 'ExportAllDeclaration':
+        exports.push(node.exported?.name ?? '*')
+        break
+
+      default:
+        break
+    }
+  }
+
+  return { imports, exports, topLevelFunctions }
+}
+
+/**
+ * Читає файл і витягає AST-факти. Read-помилка → `{ error, … }` (не кидає).
+ * @param {string} filePath абсолютний/відносний шлях до файлу
+ * @returns {{ imports: Array<{source: string, names: string[]}>, exports: string[], topLevelFunctions: string[], error?: string }} факти
+ */
+export function extractContext(filePath) {
+  let content
+  try {
+    content = readFileSync(filePath, 'utf8')
+  } catch (e) {
+    return empty(`read failed: ${e.message}`)
+  }
+  return extractContextFromSource(content, filePath)
+}

package/scripts/utils/docs/ast-extract.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: ast-extract.mjs
+resource: npm/scripts/utils/ast-extract.mjs
+docgen:
+  crc: 61e8c7bc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль аналізує вихідний код, витягуючи ключові структурні елементи. Він дозволяє отримати інформацію про імпорти, експорти та назви верхнерівневих функцій, використовуючи функції `f`, `extractContextFromSource` та `extractContext`. Функціонал працює з кодом, наданим безпосередньо або шляхом до файлу. Процес аналізу реалізований з механізмом перехоплення помилок (fail-safe), гарантуючи, що винятки не будуть викинуті назовні.
+
+## Поведінка
+
+f: витягує структурований зріз коду, включаючи імпорти, експорти та назви верхнерівневих функцій.
+extractContextFromSource: витягує структурований зріз коду з наданого вмісту, визначуючи імпорти, експорти та назви верхнерівневих функцій.
+extractContext: читає вміст файлу за вказаним шляхом і витягує з нього структуровані факти коду, обробляючи помилки під час читання.
+
+## Публічний API
+
+- f — основна логіка модуля
+- extractContextFromSource — аналізує структуру коду, наданого як текст, для отримання його граматичного представлення, не звертаючись до файлової системи
+- extractContext — читає вміст файлу та аналізує його структуру, повертаючи помилку читання замість помилки виконання
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/utils/docs/walkDir.md

@@ -3,34 +3,31 @@ type: JS Module
 title: walkDir.mjs
 resource: npm/scripts/utils/walkDir.mjs
 docgen:
-  crc: 5e5fec27
+  crc: 73503ca2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Файл `n-cursor.js` забезпечує рекурсивний обхід каталогів для скриптів перевірки, дозволяючи виконувати callback-функцію для кожного звичайного файлу. Він обходить дерево каталогів від заданого кореня, ігноруючи певні директорії (наприклад, `.git`, `node_modules`) та шляхи, вказані в `ignorePaths`. Це дозволяє автоматизувати процес аналізу конфігураційних файлів та інших ресурсів у проєкті.
+## Огляд
+
+Публічна функція `walkDir` здійснює рекурсивний пошук файлів у вказаному каталозі. Вона обходить файлову систему, ігноруючи каталоги `.git` та `node_modules`. Знаходячи кожен файл, вона передає його повний шлях у колбек для подальшої обробки. Компонент є read-only, тобто не виконує записів у файлову систему чи бази даних. При роботі з файловою системою він перехоплює помилки, забезпечуючи безпечну роботу без викидання винятків.
 
 ## Поведінка
 
-1.  Починається з заданого кореневого каталогу.
-2.  Для кожного підкаталогу в кореневому каталозі:
-    2.1. Перевіряє, чи є підкаталог у списку `ignorePaths`. Якщо так, пропускає обхід цього підкаталогу та його вмісту.
-    2.2. Якщо підкаталог не в списку `ignorePaths`, обробляє вміст підкаталогу:
-    2.2.1. Для кожного файлу в підкаталозі, викликає функцію `onFile` з шляхом до файлу.
-    2.2.2. Для кожного підкаталогу в підкаталозі, рекурсивно викликає функцію `walkDir` для обходу цього підкаталогу. Під час рекурсивного виклику, також перевіряє, чи є підкаталог у списку `ignorePaths`.
-3.  Не обробляє каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo` та `.next`.
-4.  Якщо при спробі `readdir` для каталогу виникає помилка, обхід цього каталогу припиняється.
-5.  Обхід завершується, коли всі підкаталоги та файли в заданому дереві були оброблені.
+1. Викликається функція walkDir для початку рекурсивного обходу каталогу.
+2. Система розшифровує вхідний шлях до кореня обходу.
+3. Система формує додаткові правила ігнорування на основі наданих шляхів.
+4. Система завжди ігнорує каталоги .git та node_modules.
+5. Система виконує пошук усіх файлів у каталозі, застосовуючи правила ігнорування, включаючи ті, що визначені в .gitignore.
+6. У разі виникнення помилки під час пошуку, процес обходу припиняється без генерації винятку.
+7. Для кожного знайденого файлу система викликає наданий колбек, передаючи йому повний абсолютний шлях до цього файлу.
 
 ## Публічний API
 
-- walkDir — Обходить каталог рекурсивно, ігноруючи вказані шляхи.
+walkDir — рекурсивно переглядає файли та папки, ігноруючи ті, що вказані у файлі `.gitignore`.
 
 ## Гарантії поведінки
 
-- Функція рекурсивно обходить дерево каталогів, починаючи з заданого кореня.
-- Для кожного звичайного файлу викликається переданий callback.
-- Не обходить каталоги `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
-- Може пропустити каталоги, вказані в `ignorePaths`.
-- У разі невдачі `readdir` для каталогу, функція тихо виходить без викидання помилок.
-- Функція не викидає винятки назовні.
-- У разі невдачі повертає `false` або `null`.
-- Не використовує кешування.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Свідомо пропускає шляхи: `.git`, `node_modules`.