@nitra/cursor 10.0.1 → 10.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [10.2.0] - 2026-06-15
+
+### Added
+
+- tool-surface rule — паритет «UI ↔ LLM ↔ оркестратор»: будь-яка дія фронтенду виконувана без UI через спільний каталог тулів (catalog → dispatch → UI/CLI/LLM-адаптери). Платформо-незалежне ядро; per-stack деталі делегуються правилам tauri/vue/capacitor. Авто-активація на фронтенд-залежностях. Додано per-stack секцію «Tool Surface у Tauri» в правило tauri (делегація в Rust-крейт/бінарник, два транспорти, схеми через schemars, дозволи плагінів).
+
+## [10.1.0] - 2026-06-15
+
+### Changed
+
+- Конформність-селекція: .n-cursor.json — єдине джерело правди. resolveCheckRuleIds бере активні правила прямо з конфіга (available ∩ enabled), .cursor/rules/*.mdc лишається лише fallback'ом коли конфіга нема. Прибрано дрейф «правило enabled, але .mdc нема → тихо пропущено». Per-rule whitelist-гейт у runRuleCli видалено як дубль — гейтинг живе виключно у селекції.
+
 ## [10.0.1] - 2026-06-14
 
 ### Changed

package/bin/n-cursor.js

@@ -4,19 +4,18 @@
  * n-cursor — CLI завантаження правил та перевірки проєкту
  *
  * Використання:
- *   `npx \@nitra/cursor`             — завантажити cursor-правила
- *   `npx \@nitra/cursor fix`         — автономний оркестратор: T0-auto + LLM (haiku→sonnet); convergence-loop до чистого стану [--max-iter N] [rules]
- *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
- *   `npx \@nitra/cursor fix bun`     — оркестратор лише для вказаних правил; `--json` = check-only (structured output для CI)
+ *   `npx \@nitra/cursor`             — завантажити cursor-правила (синк); якщо в корені вже є `.n-cursor.json`,
+ *                                     спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
  *   `npx \@nitra/cursor post-tool-use-fix` — точка входу PostToolUse hook Claude Code: читає stdin JSON,
  *                                     дістає `tool_input.file_path`, маршрутизує його у відповідні правила
  *                                     (`*.mjs` → `js-lint`, `*.vue` → `js-lint style-lint vue` тощо) і викликає
  *                                     `fix` лише з ними. Прописується автоматично в `.claude/settings.json`.
- *   `npx \@nitra/cursor fix`         — автономний оркестратор (meta.json: orchestrator:true): T0-auto → LLM via pi (haiku→sonnet) → check-gate → loop; [--max-iter N] [rules]
- *   `npx \@nitra/cursor lint`        — оркестратор lint-ланцюжка з кореневого `package.json` з вимірюванням часу
- *                                     кожного `lint-*` / `oxfmt` скрипта (fail-fast); канонічна заміна
- *                                     раніше ручного `lint-ga && lint-js && …` агрегатора.
+ *   `npx \@nitra/cursor lint`        — data-driven оркестратор lint+конформності по `rules/<id>/meta.json` (`lint: per-file|full`):
+ *                                     за замовчуванням fix-by-default по дельті vs origin (лише `per-file` правила); `--full` =
+ *                                     весь репо (`per-file` ∪ `full`); `--read-only` = без мутацій/LLM (CI); позиційні
+ *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`).
+ *                                     CI = `lint --read-only --full` (весь репо, нуль мутацій/LLM).
  *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
  *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
  *   `npx \@nitra/cursor lint-rego`   — канонічний lint-rego (conftest.mdc + rego.mdc):
@@ -1542,12 +1541,6 @@ try {
 
       break
     }
-    case 'lint-ci': {
-      // CI = весь репо в read-only (нуль мутацій, нуль LLM) — еквівалент `lint --read-only --full`.
-      process.exitCode = await runLint({ full: true, readOnly: true })
-
-      break
-    }
     case 'lint-ga': {
       // Канонічний lint-ga з preflight на shellcheck → actionlint → zizmor → check-ga (ga.mdc).
       // Останній крок (check-ga) async — тому await обов'язковий, інакше process.exitCode буде Promise.
@@ -1727,7 +1720,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, lint-ci, trace, doc-files, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, trace, doc-files, doc-aggregate`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "10.0.1",
+  "version": "10.2.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

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

@@ -42,8 +42,13 @@ const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
 const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
 const CATCH_RE = /catch\s*\(/
 const TRY_RE = /\btry\s*\{/
-const FALSY_RETURN_RE = /return\s+(false|null|''|"")/
-const NETWORK_RE = /\bfetch\(|https?\.|axios|got\(/
+// Falsy-return як «fail-safe» — лише коли воно в catch/error-гілці (інакше це
+// звичайний guard `if (!x) return null`, не обробка помилки). Уникає over-claim.
+const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
+// Мережа: окрім явного fetch/http, ловимо абстраговані клієнти (graphql/db/rpc/
+// octokit/.request/.query). Хибний false-negative тут = небезпечна гарантія
+// «без мережі», тож свідомо схиляємось до over-detection (м'якший бік помилки).
+const NETWORK_RE = /\bfetch\(|https?:\/\/|\bhttps?\.|axios|\bgot\(|graphql|\.request\(|\.query\(|\.mutate\(|octokit|node-fetch|undici|\bgrpc\b|websocket/i
 // Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
 // `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
 // «Кешує результати» гірша за пропуск (фабрикація > мовчання).

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+/**
+ * docgen-judge-measure.mjs — Q4 офлайн-вимірювач (spec 2026-06-14-docgen-judge-design).
+ *
+ * Міряє false-positive rate детермінованого `scoreDoc`: серед доків, що ПРОЙШЛИ
+ * (score ≥ threshold), який % сильна хмарна модель-суддя класифікує як
+ * `generic`/`inaccurate`. Це число вирішує, чи будувати рантайм-judge-гейт.
+ *
+ * Генерація: локальна (N_LOCAL_MIN_MODEL, omlx/* → прямий HTTP) — реальний пайплайн.
+ * Суддя: openai-codex/gpt-5.4-mini (сильніша хмара, ніж генератор — інакше вимір беззмістовний).
+ * Обидва — через існуючий `../../../lib/llm.mjs callLlm` (маршрутизація за префіксом).
+ *
+ * Кеш на диску (за хешем контенту) → повторні прогони не регенерують і не пересуджують.
+ *
+ * Usage:
+ *   node docgen-judge-measure.mjs <file1> <file2> ...
+ *   MEASURE_CACHE=/tmp/x N_CURSOR_DOCGEN_JUDGE_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { join } from 'node:path'
+import { generateDoc } from './docgen-gen.mjs'
+import { callLlm } from '../../../lib/llm.mjs'
+import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+
+const env = process.env
+const GEN_MODEL = env.N_LOCAL_MIN_MODEL ?? 'omlx/gemma-4-e4b-it-OptiQ-4bit'
+const JUDGE_MODEL = env.N_CURSOR_DOCGEN_JUDGE_MODEL ?? 'openai-codex/gpt-5.4-mini'
+const THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? QUALITY_THRESHOLD) || 70
+const CACHE_DIR = env.MEASURE_CACHE ?? '/tmp/docgen-judge-measure'
+const JUDGE_TIMEOUT = Number(env.MEASURE_JUDGE_TIMEOUT_MS ?? 120_000)
+
+const SYSTEM = `You are a strict technical-documentation reviewer. You receive a SOURCE file and an auto-generated Markdown DOC describing it. Classify the DOC into exactly one verdict:
+- "accurate": specific to THIS file AND every factual claim is supported by the source.
+- "generic": could describe almost any file of this kind; vague/boilerplate; lacks file-specific substance.
+- "inaccurate": contains at least one claim that is NOT supported by, or is contradicted by, the source code.
+Prefer "inaccurate" over "generic" if any claim is wrong. Respond with ONLY a JSON object, no prose:
+{"verdict":"accurate|generic|inaccurate","confidence":0.0-1.0,"reason":"<20-300 chars>","offending":["<short quote from doc>"]}`
+
+const sha = s => createHash('sha256').update(s).digest('hex').slice(0, 16)
+
+function cacheGet(key) {
+  const p = join(CACHE_DIR, key + '.json')
+  return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : null
+}
+function cacheSet(key, val) {
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
+}
+
+/** Генерує (з кешем за хешем src). */
+function genCached(file, src) {
+  const key = 'gen-' + sha(GEN_MODEL + '\0' + src)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const r = generateDoc(file, { model: GEN_MODEL })
+  const out = { md: r.md, score: r.score, issues: r.issues, degraded: r.degraded }
+  cacheSet(key, out)
+  return { ...out, cached: false }
+}
+
+/** Судить (з кешем за хешем src+doc). */
+function judgeCached(src, doc) {
+  const key = 'judge-' + sha(JUDGE_MODEL + '\0' + src + '\0' + doc)
+  const hit = cacheGet(key)
+  if (hit) return { ...hit, cached: true }
+  const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
+  const raw = callLlm([{ role: 'system', content: SYSTEM }, { role: 'user', content: user }], JUDGE_MODEL, { timeoutMs: JUDGE_TIMEOUT, temperature: 0 })
+  const a = raw.indexOf('{'), b = raw.lastIndexOf('}')
+  if (a < 0 || b < 0) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
+  const v = JSON.parse(raw.slice(a, b + 1))
+  cacheSet(key, v)
+  return { ...v, cached: false }
+}
+
+function main() {
+  const files = process.argv.slice(2).filter(f => !f.startsWith('--'))
+  if (!files.length) {
+    console.error('Usage: node docgen-judge-measure.mjs <file1> <file2> ...')
+    process.exit(2)
+  }
+  console.error(`[measure] gen=${GEN_MODEL} judge=${JUDGE_MODEL} threshold=${THRESHOLD} files=${files.length} cache=${CACHE_DIR}`)
+
+  const rows = []
+  for (const [i, file] of files.entries()) {
+    const tag = `(${i + 1}/${files.length}) ${file}`
+    let src
+    try { src = readFileSync(file, 'utf8') } catch (e) { console.error(`[skip] ${tag}: read ${e.message}`); continue }
+
+    let gen
+    try { gen = genCached(file, src) } catch (e) { console.error(`[gen-err] ${tag}: ${e.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: e.message.slice(0, 200) }); continue }
+    if (gen.score == null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
+
+    const passed = gen.score >= THRESHOLD
+    const row = { file, score: gen.score, degraded: gen.degraded, passed, genCached: gen.cached }
+    console.error(`[gen${gen.cached ? '*' : ''}] ${tag} score=${gen.score} ${passed ? 'PASS' : 'degraded'}`)
+
+    if (passed) {
+      try {
+        const v = judgeCached(src, gen.md)
+        row.verdict = v.verdict; row.confidence = v.confidence; row.reason = v.reason; row.offending = v.offending; row.judgeCached = v.cached
+        console.error(`  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`)
+      } catch (e) { row.judgeError = e.message.slice(0, 200); console.error(`  [judge-err] ${e.message.slice(0, 120)}`) }
+    }
+    rows.push(row)
+  }
+
+  // Aggregate
+  const scored = rows.filter(r => typeof r.score === 'number')
+  const passedRows = scored.filter(r => r.passed && r.verdict)
+  const byVerdict = { accurate: 0, generic: 0, inaccurate: 0 }
+  for (const r of passedRows) byVerdict[r.verdict] = (byVerdict[r.verdict] ?? 0) + 1
+  const M = passedRows.length
+  const bad = byVerdict.generic + byVerdict.inaccurate
+  const pct = n => (M ? ((100 * n) / M).toFixed(1) : '—')
+
+  const report = {
+    config: { genModel: GEN_MODEL, judgeModel: JUDGE_MODEL, threshold: THRESHOLD },
+    counts: {
+      files: files.length, generated: scored.length,
+      unsupported: rows.filter(r => r.unsupported).length,
+      genErrors: rows.filter(r => r.error === 'gen').length,
+      passedDetScorer: scored.filter(r => r.passed).length,
+      judged: M, judgeErrors: rows.filter(r => r.judgeError).length
+    },
+    falsePositiveRate: { // серед PASSED+judged
+      accurate: byVerdict.accurate, generic: byVerdict.generic, inaccurate: byVerdict.inaccurate,
+      badPct: pct(bad), inaccuratePct: pct(byVerdict.inaccurate), genericPct: pct(byVerdict.generic)
+    },
+    offenders: passedRows.filter(r => r.verdict !== 'accurate').map(r => ({ file: r.file, score: r.score, verdict: r.verdict, confidence: r.confidence, reason: r.reason })),
+    rows
+  }
+
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true })
+  const out = join(CACHE_DIR, 'report.json')
+  writeFileSync(out, JSON.stringify(report, null, 2))
+
+  console.log('\n===== Q4 MEASUREMENT =====')
+  console.log(`generated: ${report.counts.generated}/${files.length}  (unsupported=${report.counts.unsupported}, gen-errors=${report.counts.genErrors})`)
+  console.log(`passed det-scorer (score≥${THRESHOLD}): ${report.counts.passedDetScorer}   judged: ${M}`)
+  console.log(`among PASSED+judged → accurate=${byVerdict.accurate} generic=${byVerdict.generic} inaccurate=${byVerdict.inaccurate}`)
+  console.log(`>>> det-scorer FALSE-POSITIVE rate: ${pct(bad)}%  (inaccurate=${pct(byVerdict.inaccurate)}%, generic=${pct(byVerdict.generic)}%)`)
+  console.log(`decision guide: <~5% → don't build gate; >~15% → build (inaccurate-only)`)
+  console.log(`report: ${out}`)
+}
+
+main()

package/rules/js-lint-ci/js-lint-ci.mdc

@@ -1,5 +1,5 @@
 ---
-description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у lint-ci, по всьому репо.
+description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у `lint --full`, по всьому репо.
 globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
 alwaysApply: false
 version: '1.0'
@@ -8,7 +8,7 @@ version: '1.0'
 # js-lint-ci — крос-файловий ci-етап
 
 `jscpd` і `knip` аналізують увесь граф проєкту, тож мають сенс лише у повному прогоні
-`npx @nitra/cursor lint-ci` (не у швидкому `lint` по змінених файлах). Per-file режиму нема.
+`npx @nitra/cursor lint --full` (CI: `lint --read-only --full`) — не у швидкому `lint` по змінених файлах. Per-file режиму нема.
 
 Швидкий етап js-lint (oxlint/eslint) — у правилі `js-lint` (`lint: per-file`).
 

package/rules/tauri/tauri.mdc

@@ -2,7 +2,7 @@
 description: Tauri
 globs: "**/src-tauri/**,**/tauri.conf.json"
 alwaysApply: false
-version: '1.4'
+version: '1.5'
 ---
 
 У `.vscode/extensions.json` `recommendations` має містити `tauri-apps.tauri-vscode`:
@@ -66,3 +66,25 @@ exclude_globs = [
   - якщо обидва канонічні ключі (`additional_cargo_test_args`, `exclude_globs`) вже присутні — `manual cargo-mutants config preserved`, нічого не зміниться;
   - якщо якийсь канонічний ключ відсутній — додається окремим блоком у кінці файла, без зміни існуючих значень.
 - Послідовний `fix test` → `fix tauri` створює Tauri-config; повторний `fix tauri` не дублює секцій; повторний `fix test` не перетирає Tauri-tuning.
+
+## Tool Surface у Tauri (реалізація ядра `tool-surface`)
+
+Це per-stack реалізація правила **`tool-surface`** (`n-tool-surface`) для Tauri+Rust. Контракт (каталог → `dispatch` → UI/оркестратор/LLM, інваріант паритету, конверт) — у тому правилі; тут — як він лягає на Tauri.
+
+**Реальна робота живе в Rust, JS-каталог — тонкий call surface.** Handler тула не містить логіки сам — він **делегує** в native. Одна реалізація в Rust-крейті backs два споживачі:
+
+- **Бінарник** (`src-tauri` як CLI, або окремий crate-bin) — headless-вхід для оркестратора;
+- **Tauri-команда** (`#[tauri::command]`) — той самий крейт-fn, обгорнутий для UI.
+
+**Два транспорти одного каталогу** (`src/tool/transports`):
+
+- **UI (in-app):** `invoke(tool.tauri, input)` → Tauri-команда → крейт. Ключі `input` мапляться 1:1 на аргументи команди (camelCase, напр. `tasksDir`); поля вкладених struct лишаються snake_case (Tauri конвертить лише імена top-level аргументів).
+- **Оркестратор (headless):** `bin/<app>.mjs` спавнить зібраний бінарник (`<bin> <verb> …` per-verb, або уніфікований `<bin> exec '<json>'`), парсить JSON stdout.
+
+**Конверт:** Tauri-команда повертає `Result<T, String>`; адаптер мапить у `{ ok, output }` / `{ ok:false, error }`. Бінарник друкує конверт у stdout, exit ≠ 0 на `ok:false`.
+
+**Єдине джерело схем:** надавай перевагу `schemars`-derive на Rust-param-структурах → бінарник віддає маніфест (`<bin> schema`); або тримай схему в JS-каталозі й валідуй до `invoke`. **Не дублюй** контракт між Rust і JS — лише деривація + спільні тест-вектори.
+
+**Дозволи:** будь-який плагін, який смикають тули (`tauri-plugin-dialog`, `tauri-plugin-http` для локальної LLM тощо), має бути в `src-tauri/capabilities/*.json` і зареєстрований у `lib.rs` — інакше виклик тихо падає.
+
+**LLM-раннер in-app:** chat-loop ходить до OpenAI-сумісного ендпоінта через `tauri-plugin-http` fetch (бо webview-fetch обмежений CSP/capability), а тули виконує через спільний `dispatch` (той самий, що й UI).

package/rules/tool-surface/fix.mjs

@@ -0,0 +1,18 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
+  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/tool-surface/meta.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "depInAnyPackageJson", "arg": ["vue", "react", "svelte", "@angular/core", "preact", "solid-js", "@tauri-apps/api", "@capacitor/core"] } }

package/rules/tool-surface/tool-surface.mdc

@@ -0,0 +1,72 @@
+---
+description: Tool Surface — будь-яка дія фронтенду має бути виконуваною без UI (CLI + LLM) через спільний каталог тулів; UI/оркестратор/LLM — рівноправні адаптери
+alwaysApply: true
+version: '1.0'
+---
+
+# Tool Surface — паритет «UI ↔ LLM ↔ оркестратор»
+
+## Принцип
+
+**Будь-яка дія, яку людина виконує через фронтенд, мусить бути виконуваною як `tool` — без UI — бо вона організована як іменований виклик зі схемою, до якого однаково дотягуються UI, скриптовий оркестратор і LLM.**
+
+Ключовий новий споживач — **LLM**, тож одиниця називається `tool`. Фронтенд — лише один з адаптерів, а не єдині двері.
+
+## Це НЕ про «винести логіку на бекенд»
+
+Лінія поділу не «фронт ↔ бек», а:
+
+> виклик, досяжний **лише через UI-взаємодію** → погано
+> виклик, досяжний як **іменований tool зі схемою** → добре
+
+JS-логіка може лишатися на фронті — її лише треба **витягнути** з обробника події в окремий tool (ім'я + параметри + схема), який однаково кличе UI, оркестратор і LLM. Tool Surface — це **call surface**, не обов'язково бекенд.
+
+## Три шари
+
+1. **Tool Catalog** (`src/tool/`) — декларативний каталог. Кожен tool: `name`, `summary`, схема входу/виходу, `handler`. Handler **може бути фронтендовою JS-функцією** (або делегувати в native/HTTP/DB). Це **єдине джерело правди**; з нього генеруються schema-маніфест (для LLM) і типи клієнта.
+2. **Dispatch** — одна функція `dispatch(name, input) → { ok, output } | { ok: false, error }`: валідує вхід за схемою, кличе handler, повертає **уніфікований конверт**. Не прив'язана до UI-рендеру/подій.
+3. **Споживачі** (усі обов'язкові):
+   - **UI** — компонент кличе `dispatch`, без inline-логіки дії.
+   - **Оркестратор** — машинний вхід `<bin> <tool> '<json>'` (+ `schema`/`list`). Кличуть скрипти, не люди — людський CLI з verb-ами не потрібен.
+   - **LLM** — tool-маніфест із каталогу; tool_call маршрутизується в `dispatch`.
+
+## Інваріант паритету (серце правила)
+
+- **Жодної дії, досяжної лише через UI-взаємодію.** Обробник події **делегує** в `dispatch`/каталог, а не містить inline-логіку (мережа, мутація моделі, виклик бекенду).
+- Дозволено: логіка у фронтенд-коді. Заборонено: логіка **зашита** в обробник кліку/сабміту так, що дотягтись можна лише кліком.
+- Кожен tool каталогу має **усіх** споживачів (UI + оркестратор + LLM), інакше це не headless.
+
+## Єдине джерело схем
+
+Схема входу tool-а живе в каталозі (zod / JSON Schema; для Rust — `schemars`). З неї генеруються: tool-маніфест для LLM (формат залежить від провайдера — OpenAI function-calling, Anthropic tools або MCP), CLI-довідка, типи клієнта. Тул-визначення **не повинні розходитися** з каталогом — лише деривація, не дублювання.
+
+## Уніфікований конверт
+
+```jsonc
+{ "ok": true,  "output": { /* результат */ } }
+{ "ok": false, "error": { "code": "validation|not_found|io|…", "message": "…" } }
+```
+
+Оркестратор: `ok:false` → ненульовий exit. UI/LLM: `Result` / tool_result з `is_error`.
+
+## Дворівнева структура (архітектура спільна, реалізація per-stack)
+
+Архітектура **спільна**, реалізація **навмисно розходиться** за стеком. Це правило тримає платформо-незалежне **ядро**; конкретику делегують профільні правила:
+
+| Рівень | Що тут | Де |
+|---|---|---|
+| **Ядро** | принцип, інваріант паритету, контракт каталог/`dispatch`/схема/конверт, 3 споживачі | це правило |
+| **Tauri+Rust** | handler делегує в Rust-крейт/бінарник; машинний bin; `invoke`/spawn | `n-tauri` |
+| **Capacitor / pure-web** | handler — JS напряму; bin = node/bun-скрипт, що імпортує handlers | `n-capacitor` |
+| **UI-адаптер** | компонент делегує в `dispatch`, нуль inline-логіки | `n-vue` |
+
+## Конвенція файлів
+
+```
+src/tool/
+  catalog.(js|ts)     ← каталог тулів (single source): name, summary, input schema, mapping
+  dispatch.(js|ts)    ← dispatch(name, input) + валідація + конверт
+  manifest.(js|ts)    ← каталог → LLM tools ; CLI help
+  transports.(js|ts)  ← UI-транспорт (invoke/fetch) ; CLI-транспорт (spawn/import)
+bin/<app>.mjs         ← машинний вхід: <tool> '<json>' | schema | list
+```

package/schemas/rule-meta.json

@@ -8,8 +8,8 @@
   "properties": {
     "lint": {
       "type": "string",
-      "enum": ["quick", "ci"],
-      "description": "Фаза lint-кроку: quick (по змінених, у lint і lint-ci) або ci (лише lint-ci)."
+      "enum": ["per-file", "full"],
+      "description": "Scope lint-кроку: per-file (декомпозиція по змінених файлах, дельта vs origin) або full (нероздільно крос-файловий, лише `lint --full`)."
     },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",

package/scripts/lib/docs/run-rule-cli.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/lib/run-rule-cli.mjs
-  crc: 21a7b19a
+  crc: 264e7ab0
   score: 100
 ---
 
@@ -9,18 +9,15 @@ docgen:
 
 ## Огляд
 
-Файл є автономним CLI-запускачем для одного правила. Він читає конфігурацію з `.n-cursor.json`, перевіряє, чи існує запис для заданого ID у конфігурації, друкує звіт про перевірку та повертає агрегований код виходу.
+Файл є автономним CLI-запускачем для одного правила. Він друкує звіт про перевірку та повертає агрегований код виходу. Whitelist-гейту тут немає: гейтинг активних правил живе виключно у `resolveCheckRuleIds` (селекція за `.n-cursor.json`), а прямий запуск файлу правила — свідома debug/override-дія, тож виконується беззастережно.
 
 ## Поведінка
 
 1.  Викликається для запуску правила.
-2.  Читає конфігурацію з `.n-cursor.json`.
-3.  Перевіряє наявність правила у whitelist.
-4.  Якщо правило не дозволено, друкує повідомлення про пропуск.
-5.  Якщо правило дозволено, друкує повідомлення про перевірку правила.
-6.  Використовує кеш для перевірки.
-7.  Викликає функцію для виконання стандартного правила з кешем.
-8.  Повертає агрегований код виходу.
+2.  Друкує повідомлення про перевірку правила.
+3.  Використовує кеш для перевірки.
+4.  Викликає функцію для виконання стандартного правила з кешем.
+5.  Повертає агрегований код виходу.
 
 ## Гарантії поведінки
 

package/scripts/lib/fix/docs/run-fix-check.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/scripts/lib/fix/run-fix-check.mjs
-  crc: 2a0e5f0a
+  crc: 76874730
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -10,15 +10,16 @@ docgen:
 
 ## Огляд
 
-Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (включаючи завантаження конфігурації, whitelist та ізоляцію від збоїв).
+Викликає конформність-фазу `lint` (read-only), движок (`orchestrator.mjs`, `t0.mjs`) та PostToolUse-хук. Перевірка конформності виконується як пряма функція, без зовнішньої обгортки через `subprocess`. Ізоляція на рівні кожного правила зберігається: кожен файл `rules/<id>/fix.mjs` все ще запускається окремим процесом `bun` (crash-isolation). Селекція активних правил — єдине джерело: `resolveCheckRuleIds` за `.n-cursor.json`; per-rule whitelist у спавнених процесах прибрано як дубль.
 
 ## Поведінка
 
 1. Визначається наявність інструменту `conftest`.
 2. Отримується список усіх доступних ідентифікаторів правил з каталогу правил.
-3. Визначається список ідентифікаторів правил для прогону:
-    а. Якщо надано явний список правил, перевіряється, чи всі ці правила доступні.
-    б. Якщо явний список не надано, скануються файли `.cursor/rules/*.mdc` у корені проєкту. На основі знайдених файлів визначається список правил для прогону.
+3. Визначається список ідентифікаторів правил для прогону (`resolveCheckRuleIds`), де `.n-cursor.json` — єдине джерело правди:
+    а. Якщо надано явний список правил — він валідується проти доступних і звужується до активних (вимкнене правило не вмикається навіть на явний запит).
+    б. Якщо явного списку нема й конфіг є — беруться активні правила конфіга (`available ∩ enabled`); `.cursor/rules/*.mdc` ігнорується (фікс дрейфу «enabled, але .mdc нема»).
+    в. Якщо конфіга нема (open-by-default debug) — fallback на скан `.cursor/rules/*.mdc`.
 4. Якщо визначено ідентифікатори правил для прогону, для кожного ідентифікатора запускається окремий процес `bun` з файлом `fix.mjs` відповідного правила.
 5. Захоплюється вивід кожного процесу.
 6. Підраховується загальна кількість правил, що не пройшли перевірку.

package/scripts/lib/fix/run-fix-check.mjs

@@ -4,8 +4,11 @@
  * (`orchestrator.mjs`, `t0.mjs`) і PostToolUse-хук.
  *
  * Per-rule ізоляція зберігається: кожне `rules/<id>/fix.mjs` усе ще запускається окремим
- * процесом `bun` (config-loading + whitelist + crash-isolation). Прибрано лише зовнішній
- * wrapper-subprocess, що його раніше шелили оркестратор/хук.
+ * процесом `bun` (crash-isolation). Прибрано лише зовнішній wrapper-subprocess, що його
+ * раніше шелили оркестратор/хук.
+ *
+ * Селекція активних правил — виключно тут (`resolveCheckRuleIds` за `.n-cursor.json`);
+ * per-rule whitelist у спавнених процесах прибрано як дубль (див. `runRuleCli`).
  */
 import { spawnSync } from 'node:child_process'
 import { dirname, join } from 'node:path'
@@ -16,24 +19,42 @@ import { listRuleIds } from '../list-rule-ids.mjs'
 import { ensureTool } from '../ensure-tool.mjs'
 import { discoverCheckRulesFromCursorRules } from '../discover-check-rules-from-cursor.mjs'
 import { listProjectRulesMdcFiles } from '../list-project-rules-mdc.mjs'
+import { isRuleEnabled, readNCursorConfigLite } from '../read-n-cursor-config-lite.mjs'
 
 // Цей файл: npm/scripts/lib/fix/run-fix-check.mjs → npm/rules (чотири dirname угору + rules).
 const BUNDLED_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
 
 /**
- * Визначає id правил для прогону: явні (з валідацією) або discovery з `.cursor/rules/*.mdc`.
- * @param {string[]} requestedRules запитані (порожній → discovery)
- * @param {string[]} available доступні rule-id у пакеті
+ * Визначає id правил для прогону. `.n-cursor.json` — **єдине джерело правди** селекції:
+ *  - явні `requestedRules` — валідуються проти `available`, тоді звужуються до активних
+ *    (явний запит лише фільтрує всередині активних, не вмикає вимкнене правило);
+ *  - без явних і конфіг **є** — беремо саме активні правила конфіга (`available ∩ enabled`).
+ *    Це прибирає дрейф «правило в `.n-cursor.json:rules`, але `.cursor/rules/*.mdc` нема
+ *    (sync не прогнаний) → раніше тихо пропускалось»;
+ *  - без явних і конфіга **нема** — open-by-default debug: fallback на зматеріалізовані
+ *    `.cursor/rules/*.mdc` (єдиний сигнал «що встановлено», коли немає whitelist).
+ *
+ * Per-rule дубль-гейту (`runRuleCli → isRuleEnabled`) більше немає — гейтинг живе лише тут.
+ * @param {string[]} requestedRules запитані (порожній → auto-селекція)
+ * @param {string[]} available доступні rule-id у пакеті (алфавітно)
  * @param {string} cwd корінь
  * @returns {Promise<string[]>} id для прогону (можливо порожній)
  * @throws {Error} на невідомих явно заданих правилах
  */
-async function resolveCheckRuleIds(requestedRules, available, cwd) {
+export async function resolveCheckRuleIds(requestedRules, available, cwd) {
+  const config = await readNCursorConfigLite(cwd)
+
   if (requestedRules.length > 0) {
     const unknown = requestedRules.filter(id => !available.includes(id))
     if (unknown.length > 0) throw new Error(`Unknown rules: ${unknown.join(', ')}`)
-    return requestedRules
+    return requestedRules.filter(id => isRuleEnabled(config, id))
   }
+
+  if (config.exists) {
+    return available.filter(id => isRuleEnabled(config, id))
+  }
+
+  // Конфіга нема → fallback на зматеріалізоване (debug / open-by-default).
   const mdcFiles = await listProjectRulesMdcFiles(cwd)
   if (mdcFiles.length === 0) return []
   return discoverCheckRulesFromCursorRules(available, mdcFiles)

package/scripts/lib/run-rule-cli.mjs

@@ -1,14 +1,17 @@
 /**
  * Standalone CLI runner для одного правила. Викликається з `rules/<id>/fix.mjs`
  * у блоці `if (import.meta.main)` — це робить `bun rules/<id>/fix.mjs` повним
- * еквівалентом старого `npx \@nitra/cursor fix <id>`: читає `.n-cursor.json`,
- * перевіряє whitelist, друкує summary, повертає aggregated exit-code.
+ * еквівалентом `npx \@nitra/cursor fix <id>`: друкує summary, повертає aggregated exit-code.
+ *
+ * **Без whitelist-гейту.** Гейтинг активних правил — єдине джерело: `resolveCheckRuleIds`
+ * (`scripts/lib/fix/run-fix-check.mjs`) за `.n-cursor.json`. Прямий `bun rules/<id>/fix.mjs` —
+ * свідомий запуск саме цього правила (debug / override), тож виконується беззастережно;
+ * усі автоматичні шляхи (lint-конформність, orchestrator, t0, hook) уже спавнять лише активні.
  *
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.
  */
 import { basename } from 'node:path'
 
-import { isRuleEnabled, readNCursorConfigLite } from './read-n-cursor-config-lite.mjs'
 import { runStandardRule } from './run-standard-rule.mjs'
 import { getOrCreateWalkCache } from '../utils/walk-cache.mjs'
 
@@ -21,16 +24,10 @@ const PACKAGE_NAME = '@nitra/cursor'
 
 /**
  * @param {string} ruleDir абсолютний шлях до `rules/<id>/`
- * @returns {Promise<number>} 0 — OK або правило не enabled; 1 — порушення
+ * @returns {Promise<number>} 0 — OK; 1 — порушення
  */
 export async function runRuleCli(ruleDir) {
   const ruleId = basename(ruleDir)
-  const config = await readNCursorConfigLite()
-
-  if (!isRuleEnabled(config, ruleId)) {
-    console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — правило не в \`.n-cursor.json:rules\`. Пропущено.\n`)
-    return 0
-  }
 
   console.log(`\n🔍 ${PACKAGE_NAME} fix ${ruleId} — перевірка правила\n`)