@nitra/cursor 3.26.0 → 3.28.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [3.28.0] - 2026-06-06
+
+### Added
+
+- lib/models.mjs: global model tier classification (LOCAL_MIN/AVG/MAX, CLOUD_MIN/AVG/MAX) via N_*_MODEL env vars; fix llm-worker uses CLOUD_MIN/AVG by default
+
+### Changed
+
+- fix orchestrator: concise output — single line when clean, details only when issues occur
+- llm-worker: rename MODEL_HAIKU/SONNET → MODEL/MODEL_HEAVY, helpful error when pi has no API key for provider
+
+## [3.27.0] - 2026-06-06
+
+### Added
+
+- add fix-t0 CLI command: T0-auto pattern library for n-fix orchestrator (deterministic vscode-ext-add and rm-forbidden-file fixes, 0 LLM tokens)
+- add fix-run: autonomous n-fix orchestrator (convergence-loop fix-t0+LLM, haiku→sonnet escalation, no agent needed)
+
 ## [3.26.0] - 2026-06-06
 
 ### Added

package/bin/n-cursor.js

@@ -5,14 +5,15 @@
  *
  * Використання:
  *   `npx \@nitra/cursor`             — завантажити cursor-правила
- *   `npx \@nitra/cursor fix`         — перевірити правила з `.cursor/rules/*.mdc`, для яких у пакеті є `fix.mjs`/policy;
+ *   `npx \@nitra/cursor fix`         — автономний оркестратор: T0-auto + LLM (haiku→sonnet); convergence-loop до чистого стану [--max-iter N] [rules]
  *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
- *   `npx \@nitra/cursor fix bun`     — перевірити лише вказані правила (ігнорує `.cursor/rules/`)
+ *   `npx \@nitra/cursor fix bun`     — оркестратор лише для вказаних правил; `--json` = check-only (structured output для CI)
  *   `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 && …` агрегатора.
@@ -1596,12 +1597,14 @@ try {
   await ensureNitraCursorInRootDevDependencies(cwd())
   switch (command) {
     case 'fix': {
-      // --json: компактний {total, failed, rules:[{ruleId, ok, output}]} у stdout для скілу n-fix.
-      await runFixCommand(
-        args.filter(a => a !== '--json'),
-        { json: args.includes('--json') }
-      )
-
+      const { runOrchestratorCli } = await import('../skills/fix/js/orchestrator.mjs')
+      process.exitCode = await runOrchestratorCli(args, cwd())
+      break
+    }
+    case '_fix-check': {
+      // Внутрішня команда оркестратора — не є публічним API.
+      // Повертає JSON {total, failed, rules:[{ruleId, ok, output}]} у stdout.
+      await runFixCommand(args, { json: true })
       break
     }
     case 'check': {
@@ -1709,6 +1712,23 @@ try {
 
       break
     }
+    case 'fix-run': {
+      // Backward-compatibility alias → перенаправляємо на `fix`.
+      console.warn(`⚠️  \`fix-run\` deprecated — використовуйте \`fix\``)
+      const { runOrchestratorCli } = await import('../skills/fix/js/orchestrator.mjs')
+      process.exitCode = await runOrchestratorCli(args, cwd())
+      break
+    }
+    case 'fix-t0': {
+      // n-cursor fix-t0 [rule...] — T0-auto рівень n-fix оркестратора.
+      // Запускає fix --json, знаходить violation-output із детермінованим паттерном
+      // (vscode-ext-add, rm-forbidden-file тощо), застосовує програмний фікс (0 LLM),
+      // перевіряє check-gate. Exit 0 = усі T0-паттерни закриті; 1 = є решта для LLM.
+      const { runT0AutoCli } = await import('../skills/fix/js/t0.mjs')
+      process.exitCode = await runT0AutoCli(args, cwd())
+
+      break
+    }
     case 'change': {
       const { runChangeCli } = await import('../rules/release/change.mjs')
       process.exitCode = await runChangeCli(args)
@@ -1780,7 +1800,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, lint-ci, flow, trace, graph, docgen`
+        `   Очікується: (без аргументів) синхронізація правил, fix, check, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, coverage, coverage-fix, taze, start-check, fix-t0, change, release, skill, worktree, lint-ci, flow, trace, graph, docgen`
       )
       process.exitCode = 1
     }

package/package.json

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

package/rules/abie/js/applies.mjs

@@ -1,8 +1,4 @@
-/**
- * Applies-гейт правила abie: rule-level через `isAbieRuleEnabled` (поле `rules` у `.n-cursor.json`).
- * Якщо повертає `false` — CLI пропускає всі концерни (JS і policy) цього правила.
- * `check()` друкує тільки context-pass; решта концернів роблять справжню роботу.
- */
+/** @see ./docs/applies.md */
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 
 import { isAbieRuleEnabled } from '../lib/enabled.mjs'

package/rules/abie/js/env_dns.mjs

@@ -1,12 +1,4 @@
-/**
- * Скан env-файлів abie (`*.dev.env`, `*.ua.env`): кожен внутрішньокластерний URL
- * `http://<svc>.<ns>.svc.<dns>` має відповідати кластеру за іменем файла:
- *   - `dev.env` → `abie-dev.internal` + `dev-*` namespace
- *   - `ua.env`  → `abie-ua.internal` + `ua-*` namespace
- *
- * Файл `.env` без імені (локальний для розробника) — виключено.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/env_dns.md */
 import { readFile } from 'node:fs/promises'
 import { basename, relative } from 'node:path'
 

package/rules/abie/js/firebase_hosting.mjs

@@ -1,8 +1,4 @@
-/**
- * Перевірка abie: у **підкаталогах першого рівня** (без `.git`/`node_modules`) не має бути
- * `.firebaserc`, `firebase.json`, `.firebase/` (abie.mdc — Firebase Hosting заборонено).
- * У самому корені репозиторію ці імена не перевіряються (можуть бути від суміжних проєктів).
- */
+/** @see ./docs/firebase_hosting.md */
 import { existsSync } from 'node:fs'
 import { readdir } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/abie/js/hc_pairing.mjs

@@ -1,11 +1,4 @@
-/**
- * Перевірка abie: для кожного каталогу з `kind: Deployment` під `k8s/` поруч має бути `hc.yaml`
- * з коректним modeline (yaml-language-server $schema).
- *
- * Це JS-частина (FS-парність + modeline). Структурну валідацію `HealthCheckPolicy`
- * (apiVersion, requestPath, port, targetRef з суфіксом `-hl`) робить CLI через
- * `policy/health_check_policy/target.json` (walkGlob по hc.yaml у k8s-дереві).
- */
+/** @see ./docs/hc_pairing.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'

package/rules/abie/js/ua_http_route.mjs

@@ -1,13 +1,4 @@
-/**
- * Якщо в каталозі пакета (батько `k8s/`) є `vite.config.{js,mjs,ts}`, у `ua/kustomization.yaml`
- * має бути inline-patch HTTPRoute (непорожній `target.name`): `/spec/hostnames` (домени abie),
- * `/spec/parentRefs/0/namespace` (`ua` або `ua-*`).
- *
- * Для спільних сервісів (`auth-run-hl`, `file-link-hl`) у base-HTTPRoute пакета — кожен `backendRef`
- * має `namespace: dev`; в overlay patch — JSON6902 на `/spec/rules/…/backendRefs/…/namespace` зі
- * `value: ua`. Кількість patch-ів = кількість таких посилань у base.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/ua_http_route.md */
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 

package/rules/abie/js/ua_node_selector.mjs

@@ -1,11 +1,4 @@
-/**
- * Якщо в дереві `k8s/` пакета є `Deployment`, у `ua/kustomization.yaml` має бути inline-patch
- * на `Deployment` з `path /spec/template/spec/nodeSelector` і `preem: false` (abie.mdc).
- *
- * Структурні обмеження JSON6902 (заборона `remove + add` на той самий path) перевіряє k8s.mdc /
- * `k8s.kustomization` rego — тут лише abie-специфічне.
- * @param {string} [cwd] корінь репозиторію
- */
+/** @see ./docs/ua_node_selector.md */
 import { readFile } from 'node:fs/promises'
 import { relative } from 'node:path'
 

package/rules/adr/js/hooks.mjs

@@ -1,23 +1,4 @@
-/**
- * Перевіряє вимоги правила adr.mdc: ADR Stop-hook'и `capture-decisions.sh` і
- * `normalize-decisions.sh` у Claude Code.
- *
- * Очікування:
- * - `.claude/hooks/capture-decisions.sh` та `.claude/hooks/normalize-decisions.sh`
- *   існують і байт-у-байт збігаються з канонічними `.claude-template/hooks/*`
- *   пакета (sync керує файлами повністю).
- * - `.claude/settings.json` (project-shared) має managed-групи у `hooks.Stop` для
- *   обох скриптів (маркери у `command` — самі шляхи до скриптів).
- * - `.cursor/hooks.json` має managed entries у `hooks.stop` для обох скриптів, щоб
- *   Cursor Agent теж запускав ADR capture/normalize після завершення відповіді.
- * - `.claude/settings.local.json` (якщо існує) НЕ має дублів цих managed-груп —
- *   після переходу на project-shared такі записи створили б два запуски на одну подію.
- * - `.gitignore` у корені містить шаблон, який покриває
- *   `.claude/hooks/capture-decisions.log` і `.claude/hooks/normalize-decisions.log`.
- *
- * LLM CLI (`claude` або `cursor-agent`) у `PATH` — інформативна перевірка: якщо жодного
- * немає, скрипт працює, але мовчки виходить, тому це warning, а не fail.
- */
+/** @see ./docs/hooks.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { delimiter, dirname, join } from 'node:path'

package/rules/bun/js/layout.mjs

@@ -1,22 +1,4 @@
-/**
- * Перевіряє відповідність репозиторію правилам Bun (bun.mdc).
- *
- * **Що тут лишилося** (FS / cross-file — не покривається conftest):
- *  - наявність `bun.lock`, `bunfig.toml`, `package.json` у корені (FS-existence);
- *  - заборонені lockfile та артефакти yarn/pnpm (`package-lock.json`, `yarn.lock`,
- *    `pnpm-lock.yaml`, `.yarnrc.yml`, директорія `.yarn/`);
- *  - двосторонній зв'язок `.n-cursor.json:rules` ↔ `package.json:scripts` для правил із
- *    `lint-<id>` (`docker`, `k8s`): rule увімкнено → скрипт мусить існувати; rule
- *    відсутнє (або в `disable-rules`) → скрипту та згадки `bun run lint-<id>` у
- *    агрегованому `scripts.lint` бути **не може** (інакше `bun run lint` падатиме
- *    на правилі, яке у конфізі вимкнено).
- *
- * **Що покрила Rego** (`npx \@nitra/cursor check`):
- *  - `npm/policy/bun/bunfig/` — `[install].linker == "hoisted"` у `bunfig.toml`;
- *  - `npm/policy/bun/package_json/` — відсутність `packageManager` / `dependencies`
- *    у кореневому `package.json`, у `devDependencies` лише `@nitra/*`, агрегований
- *    `lint`-скрипт покриває всі `lint-*` через `bun run` і завершується `&& oxfmt .`.
- */
+/** @see ./docs/layout.md */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'

package/rules/capacitor/js/platforms.mjs

@@ -1,26 +1,4 @@
-/**
- * Перевіряє відповідність проєкту правилам capacitor.mdc для застосунків **Capacitor**.
- *
- * Якщо у репозиторії **немає** ознак Capacitor (див. наведене) — вихід **0**, перевірка не застосовується.
- *
- * **Ознака Capacitor:** наявні **`capacitor.config.json`**, **`capacitor.config.ts`**, **`capacitor.config.mjs`**
- * (у корені) **або** у будь-якому `package.json` (рекурсивно, з пропуском типових каталогів) оголошено
- * хоча б одну залежність **`@capacitor/…`** (у **`dependencies`**, **`devDependencies`**, опційно
- * **`optionalDependencies`**, **`peerDependencies`**).
- *
- * **Версія мінімум 8:** у кожному `package.json`, де вказано **`@capacitor/core`**, діапазон версії
- * мусить допускати лише **Capacitor 8+** (оцінка мінімального **major** з рядка діапазону npm, зокрема
- * `||` і діапазонів через `-` у спрощеному вигляді). **`*`**, **latest** та нерозпізнані випадки — **порушення**:
- * варто задати явний діапазон, наприклад **`^8.0.0`**. Якщо оголошено `capacitor.config.*` без жодного
- * **`@capacitor/core`** у дереві `package.json` — також помилка.
- *
- * **iOS:** зазвичай **без** **Podfile** поза **Pods** (тільки **SPM**). **@nitra/**-плагіни за політикою **SPM** —
- * їх **не** перелічуємо й **не** перевіряємо. Якщо **Podfile** є, його можна зареєструвати як **виняток**
- * (див. **capacitor.mdc**): у кореневому **`package.json`** або
- * **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**, об’єкт **nitra** з
- * **`iosCocoaPodsBecausePluginsLackSpm: true`** (або **`iosCocoaPodsAllowed: true`**); тоді **Podfile** **не** fail.
- * Якщо **`ios/`** **немає** — iOS-умови не застосовуються.
- */
+/** @see ./docs/platforms.md */
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join, relative } from 'node:path'

package/rules/changelog/js/consistency.mjs

@@ -1,32 +1,4 @@
-/**
- * Перевіряє, що кожен workspace із релізно-релевантними змінами зафіксував їх через
- * change-файл `<ws>/.changes/*.md` — єдиний дозволений артефакт зміни. Bump `version`
- * і генерацію `CHANGELOG.md` робить виключно `n-cursor release` у CI на `main`.
- *
- * Інваріант (на будь-якій гілці): `version` у дереві не має **випереджати** базу. Лише
- * drift **уперед** (`version` > опублікованої в реєстрі / > git-бази) — ручний bump поза
- * CI — завалює перевірку, навіть із change-файлом. Version **позаду** бази (локаль відстала
- * від уже опублікованого CI-релізу, ще не зроблено `git pull`) — НЕ порушення: це не ручний
- * bump, а git і так не дасть запушити non-fast-forward. Pass лише коли є change-файл, а
- * version не випереджає базу; зміни без change-файлу — fail.
- *
- * Дві моделі бази — на рівні воркспейсу (див. n-changelog.mdc):
- *
- * 1) **registry-published** (npm: `name` + `files`, не `private`; Python: `project.name` +
- *    статична `project.version`): база = опублікована версія в npm / PyPI.
- * 2) **local-only** (приватні npm без `files`, Python без імені/версії для реєстру):
- *    feature-гілка — `merge-base` з `dev`, інакше з `main`; на `main` — diff від
- *    `origin/main` (або `HEAD~1` без remote).
- *
- * Усі `git` і зовнішні виклики — через `execFile` / `fetch`, без shell-інтерполяції.
- *
- * **Autofix-режим** (env `N_CURSOR_CHANGELOG_AUTOFIX=1`, виставляється лише кроком
- * `npm-changelog` у `hk.pkl` для pre-commit): замість `fail` на відсутній change-файл
- * правило саме створює його через `writeChange()` з дефолтами (`bump=patch`,
- * `section=Changed`, `message` = subject останнього коміту) і ставить у git-індекс, щоб
- * коміт не падав. Поза хуком (CI, ручний `fix`/`check`, read-only review) режим вимкнено —
- * поведінка лишається fail-on-missing, тож CI не плодить артефактів.
- */
+/** @see ./docs/consistency.md */
 import { execFile } from 'node:child_process'
 import { join } from 'node:path'
 import { promisify } from 'node:util'

package/rules/ci4/js/marksman_config.mjs

@@ -1,22 +1,4 @@
-/**
- * Концерн `marksman_config` правила ci4 (ci4.mdc): копіює canonical
- * `.marksman.toml` baseline у корінь cwd, якщо файлу ще немає.
- *
- * Marksman LSP читає `.marksman.toml` для визначення workspace-роота,
- * GLFM-флага (GitHub-Flavored Markdown), стилю wiki-links і code actions.
- * Дефолти marksman не вмикають GLFM і використовують `title-slug-ref` —
- * але portable subset з ci4.mdc вимагає GLFM (alerts/таблиці/todo) +
- * `file-stem` (ADR slug == ім'я файла). Без явного конфіга частина
- * marksman-функцій працює інакше, ніж задокументовано у правилі.
- *
- * Idempotent: якщо `.marksman.toml` вже існує (навіть з кастомним вмістом)
- * — не перетирається, тільки рапортується факт існування. Ручні правки
- * користувача зберігаються між прогонами.
- *
- * Файл скопійовано в `cwd`, бо marksman визначає workspace-root за
- * розташуванням свого `.marksman.toml`. У корені репо марксман бачить
- * і docs/, і README.md усіх workspaces одним workspace-ом.
- */
+/** @see ./docs/marksman_config.md */
 import { existsSync } from 'node:fs'
 import { copyFile } from 'node:fs/promises'
 import { dirname, join, relative } from 'node:path'

package/rules/docker/js/lint.mjs

@@ -1,37 +1,4 @@
-/**
- * Запускає hadolint для Dockerfile / Containerfile у всьому репозиторії (див. docker.mdc).
- *
- * Додатково переконуються, що образи `oven/bun`, `alpine`, `nginx`, `node` з Docker Hub
- * вказуються через `mirror.gcr.io` (див. `./docker-mirror.mjs`).
- *
- * Також перевіряє, що Dockerfile/Containerfile має **multistage build** і що фінальний stage
- * використовує дозволений runtime-образ (див. docker.mdc):
- * - backend: `mirror.gcr.io/library/alpine:*`, `scratch`, `mirror.gcr.io/library/debian:` з тегом, що
- *   містить `slim` (не повний `debian:bookworm`), за винятком PHP/Python — `mirror.gcr.io/library/php:*` або
- *   `mirror.gcr.io/library/python:*`
- * - frontend: `mirror.gcr.io/nginxinc/nginx-unprivileged:*`, `mirror.gcr.io/openresty/openresty:*`
- *
- * Якщо в Dockerfile є крок `bun install` і це не frontend-образ (фінальний stage — alpine),
- * то очікується компіляція в один бінарник через `bun build --compile` у build stage, а у
- * фінальному stage не повинно залишатися build tooling (Bun/Node).
- *
- * Виняток — проєкти з нативним `.node`-аддоном (sharp/@img/argon2), який вантажиться через
- * динамічний `require`: їх НЕ можна компілювати (`bun build --compile` не вшиває нативний
- * біндинг → краш у рантаймі). Для них канон — node_modules + `bun <entry>` на базі
- * `mirror.gcr.io/oven/bun:alpine` (див. `../lib/docker-native-addon.mjs`).
- *
- * Мета — щоб у фінальному образі не було build tooling (Bun/Node та залежностей), а лише
- * дозволений runtime (alpine, scratch, debian slim, за потреби php/python, nginx або openresty).
- *
- * Для nginx-образів (`mirror.gcr.io/nginxinc/nginx-unprivileged`) у будь-якому `FROM` очікується
- * тег `alpine-slim` (docker.mdc: мінімальні образи), не `latest` /
- * `alpine` / інші. `nginx-unprivileged` запускається від не-root користувача (uid=101) без явного
- * `USER` у Dockerfile — перевірка non-root для нього пропускається.
- *
- * Знаходить Dockerfile, Dockerfile.*, Containerfile, Containerfile.*; пропускає node_modules, .git
- * тощо. hadolint — нативний бінарник через `ensureTool` (PATH/кеш/авто-install; без docker run).
- * Кореневий .hadolint.yaml підхоплюється hadolint автоматично.
- */
+/** @see ./docs/lint.md */
 import { readFile } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 

package/rules/ga/docs/fix.md

@@ -1,158 +1,25 @@
-# fix.mjs — точка входу правила `ga`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/ga/fix.mjs` — це **подвійна точка входу** (dual-mode entry-point) для правила з ідентифікатором `ga` (Google Analytics) у проєкті `@nitra/cursor`. Файл реалізує дві ролі одночасно:
+Цей файл запускає процес перевірки наявності та стану необхідних системних ресурсів. Він забезпечує швидку оцінку готовності системи до подальшої роботи, використовуючи кешовані дані для прискорення процесу. Результати перевірки використовуються для прийняття рішень щодо подальших дій.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку імпортує оркестратор CLI (`bin/cursor.mjs` або інші правила) для запуску прогону у складі сукупної команди (наприклад, `npx @nitra/cursor fix`).
-2. **Standalone mode** — якщо файл запущено напряму через `bun npm/rules/ga/fix.mjs` (або `node ...`), він самостійно ініціалізує CLI-обгортку (`runRuleCli`) і завершує процес із кодом виходу, придатним для CI/IDE.
+## Поведінка
 
-Логіка самого правила інкапсульована в утиліті `runStandardRule`, яка послідовно виконує стандартний пайплайн усіх «standard»-правил репозиторію:
+1.  Ініціалізує контекст прогону.
+2.  Викликає стандартне правило, використовуючи контекст.
+3.  Якщо код виконується як окремий CLI-скрипт, то:
+    1.  Викликає оркестрацію правил.
+    2.  Повертає код завершення процесу.
 
-- **applies** — перевірка, що правило застосовне до поточного workspace/файлів (за патернами з `meta.json`);
-- **JS-concerns** — запуск перевірок (`check-*.mjs`) і авто-фіксерів (`fix-*.mjs`) із підтек `js/`, `lint/`;
-- **policy** — застосування policy-перевірок із підтеки `policy/`;
-- **mdc-refs** — валідація посилань всередині `ga.mdc` (cross-link integrity).
+## Публічний API
 
-Файл свідомо мінімалістичний: він **не містить власної бізнес-логіки**, лише делегує виконання у спільні бібліотеки `scripts/lib/*`. Це гарантує однакову поведінку для всіх правил пакету.
+- run — Запускає стандартне правило, враховуючи контекст та перетворюючи його на JS-коду, політику та посилання на MDC.
+- Library mode — Викликається через CLI-оркестрацію за допомогою імпорту та функції `run`.
 
-## Експорти / API
+## Гарантії поведінки
 
-| Експорт | Тип                               | Опис                                                                                                                               |
-| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?): Promise<number>` | Бібліотечний вхід; запускає стандартний пайплайн правила в контексті переданого `ctx`. Повертає exit-code (0 — OK, 1 — порушення). |
-
-Default-експорту немає. Файл не реекспортує жодних інших символів.
-
-## Функції
-
-### `run(ctx)`
-
-Бібліотечний інтерфейс правила. Дозволяє оркестратору CLI або іншим правилам запустити перевірку `ga` без створення нового процесу.
-
-**Сигнатура:**
-
-```js
-export function run(ctx)
-```
-
-**Параметри:**
-
-- `ctx` (`RuleContext`, опційний) — контекст прогону, типізований через JSDoc-імпорт з `../../scripts/lib/run-standard-rule.mjs`. Типово містить:
-  - `walkCache` — кеш обходу файлів (щоб уникнути повторного `readdir` між правилами в одній сесії);
-  - інші поля, передбачені реалізацією `runStandardRule` (репорти, прапорці dry-run тощо).
-
-**Повертає:**
-
-- `Promise<number>` — числовий код виходу:
-  - `0` — правило не знайшло порушень або всі знайдені були автоматично виправлені;
-  - `1` — залишилися порушення, які потребують ручного втручання.
-
-**Side effects:**
-
-- Може читати файли проєкту (через walkCache і внутрішні `check-*.mjs`/`fix-*.mjs`);
-- Може **писати** файли (auto-fix у режимі за замовчуванням; `fix-*.mjs` із підтек `js/`, `lint/`, `policy/`);
-- Може писати в `stdout`/`stderr` (репорти, попередження, summary), залежно від конфігурації `runStandardRule`;
-- Не викликає `process.exit` напряму — повертає код виходу як значення Promise.
-
-**Внутрішня реалізація:**
-
-```js
-return runStandardRule(import.meta.dirname, ctx)
-```
-
-Передає **абсолютний шлях до директорії правила** (`import.meta.dirname` — Node/Bun-нативний спосіб отримати `__dirname` в ESM) і контекст. `runStandardRule` сам визначить ID правила за назвою теки (`ga`), завантажить `meta.json`, `ga.mdc` і виконає пайплайн.
-
-### Standalone-блок (top-level `if`)
-
-Не є експортованою функцією, але є важливою частиною API файлу.
-
-**Логіка:**
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-**Поведінка:**
-
-- `isRunAsCli(import.meta.url)` повертає `true`, якщо файл був запущений як основний модуль (а не імпортований). Це Bun/Node-сумісна заміна звичайного для CommonJS `require.main === module`.
-- У такому разі викликається `runRuleCli(import.meta.dirname)` — обгортка, що додає до простого `run(ctx)`:
-  - парсинг аргументів командного рядка (наприклад, `--dry-run`, `--scope`);
-  - завантаження користувацького конфігу (`.cursorrc`, whitelist-файлів);
-  - друк фінального summary з кодом виходу.
-- Результат (`number`) передається у `process.exit(...)`, тож виклик `bun npm/rules/ga/fix.mjs` повертає shell-у точний exit-code для CI/IDE-інтеграції.
-
-**ESLint-винятки** (інлайн-коментар):
-
-- `n/no-process-exit` (плагін `eslint-plugin-n`) і `unicorn/no-process-exit` — обидва зазвичай забороняють `process.exit`, оскільки він обриває async-операції без cleanup. Тут виняток виправданий: це **єдиний standalone entry-point**, який мусить повернути exit-code саме через `process.exit`, інакше CI не зможе розрізнити успіх/провал.
-
-**Top-level `await`:**
-
-- Використовується `await runRuleCli(...)` на верхньому рівні модуля — це валідно для ESM (`.mjs`) у сучасних Node.js (≥14.8) і Bun. Без `await` `process.exit` отримав би `Promise` замість числа.
-
-## Залежності
-
-### Внутрішні (workspace)
-
-| Модуль              | Шлях                                      | Експорти, що використовуються                                       |
-| ------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
-| `run-rule-cli`      | `../../scripts/lib/run-rule-cli.mjs`      | `isRunAsCli`, `runRuleCli`                                          |
-| `run-standard-rule` | `../../scripts/lib/run-standard-rule.mjs` | `runStandardRule`; також імпортується тип `RuleContext` через JSDoc |
-
-Шляхи відносні до `npm/rules/ga/fix.mjs`, тобто `../../scripts/lib/` → `npm/scripts/lib/`.
-
-### Зовнішні / runtime
-
-- **Node.js / Bun ESM API**: `import.meta.url`, `import.meta.dirname` (вимагає Node ≥20.11 або Bun, де `dirname` доступний нативно).
-- **`process`**: глобальний об'єкт (`process.exit`).
-
-Жодних npm-залежностей файл напряму не імпортує — всі стороні пакети підтягуються транзитивно через `scripts/lib/*`.
-
-## Потік виконання / Використання
-
-### Сценарій 1: запуск через `@nitra/cursor` (library mode)
-
-1. Користувач виконує `npx @nitra/cursor fix ga` або `npx @nitra/cursor fix` (усі правила).
-2. CLI-бінарник пакету (`bin/cursor.mjs` або аналог) динамічно імпортує `npm/rules/ga/fix.mjs`.
-3. Оскільки модуль імпортовано (а не запущено), `isRunAsCli(import.meta.url)` → `false`, standalone-блок не виконується.
-4. CLI викликає експортовану `run(ctx)` із заздалегідь підготованим контекстом (`walkCache`, прапорці).
-5. `run` повертає `Promise<number>` — CLI агрегує його з результатами інших правил у фінальний exit-code.
-
-### Сценарій 2: прямий запуск файлу (standalone)
-
-1. Розробник або CI виконує `bun npm/rules/ga/fix.mjs` (зручно для дебагу одного правила).
-2. Модуль завантажується як основний; `isRunAsCli(import.meta.url)` → `true`.
-3. Виконується `await runRuleCli(import.meta.dirname)`:
-   - парсяться CLI-аргументи;
-   - завантажується конфіг/whitelist;
-   - всередині також викликається `runStandardRule` (так само як у library-режимі), але з повним «end-to-end» обрамленням;
-   - виводиться summary.
-4. `process.exit(<code>)` завершує процес із отриманим exit-code (0/1).
-
-### Стандартний пайплайн `runStandardRule` (у обох сценаріях)
-
-Послідовність (детальніше — в документації `runStandardRule`):
-
-1. **applies** — `meta.json` визначає, чи треба запускати правило в поточному workspace; якщо ні — ранній вихід з кодом 0.
-2. **JS-concerns** — обходяться підтеки правила (`js/`, `lint/`), виконуються пари `check-*.mjs` + `fix-*.mjs`. Якщо `check` повернув порушення, відповідний `fix` пробує їх прибрати.
-3. **policy** — з підтеки `policy/` запускаються policy-чекери (зазвичай це декларативні правила, без auto-fix або з обмеженим fix).
-4. **mdc-refs** — валідація, що в `ga.mdc` (markdown-документ із описом правила) посилання на `js/`, `lint/`, `policy/` коректні (немає «битих» референсів).
-5. Агрегується фінальний exit-code: `0`, якщо всі стадії чисті; `1` — інакше.
-
-### Як додати/змінити поведінку правила `ga`
-
-Файл `fix.mjs` змінювати **не треба** — він універсальний. Щоб модифікувати поведінку правила:
-
-- додайте/змініть `check-*.mjs` і `fix-*.mjs` у підтеках `js/`, `lint/` теки `ga/`;
-- оновіть `policy/`-чекери для декларативних обмежень;
-- актуалізуйте `ga.mdc` (опис для людини/LLM) і `meta.json` (applies, scope, прапорці);
-- запустіть `bun npm/rules/ga/fix.mjs` для локальної перевірки.
-
-### Обмеження та інваріанти
-
-- Файл **повинен** залишатися мінімалістичним — будь-яка бізнес-логіка в `fix.mjs` правила вважається порушенням архітектури «standard rule» (див. `n-ci4.mdc`).
-- Не можна вилучати `if (isRunAsCli(...))`-блок: інакше прямий запуск файлу не поверне CI exit-code.
-- Не можна замінювати `process.exit` на `return` у standalone-блоці: top-level `return` у ESM-модулі недопустимий, а без `process.exit` процес не отримає правильний код.
-- ESLint-винятки (`n/no-process-exit`, `unicorn/no-process-exit`) застосовуються **лише** до рядка з `process.exit` — їх не слід розширювати на інші місця.
+- Запускає процес.
+- Кеш зберігає результати попередніх прогонів.
+- Результат залежить від попередніх прогонів.
+- Немає взаємодії з мережею.