@nitra/cursor 5.3.4 → 5.4.0

package/rules/npm-module/js/docs/rule_meta.md

@@ -1,137 +1,35 @@
+---
+docgen:
+  source: npm/rules/npm-module/js/rule_meta.mjs
+  crc: fa29bd00
+  score: 100
+---
+
 # rule_meta.mjs
 
 ## Огляд
 
-Модуль `rule_meta.mjs` реалізує перевірку метаданих правил пакета `@nitra/cursor`. Він є частиною концерну правила `npm-module` й обслуговує валідацію файлів `npm/rules/<id>/meta.json` у репозиторії пакета.
-
-Логіка перевірки покриває такі інваріанти для кожного підкаталогу `npm/rules/<id>/`:
-
-- наявність валідного `meta.json`;
-- коректність поля `auto`, якщо воно присутнє (розпізнаваність специфікації через `parseRuleAutoSpec`: значення `"завжди"`, масив, `{glob}` або `{predicate}`);
-- для специфікації `{predicate}` — наявність відповідного імені у реєстрі `RULE_PREDICATES`;
-- коректність поля `lint`, якщо воно присутнє (`"quick"` чи `"ci"`), з обовʼязковою наявністю файлу `js/lint.mjs` у каталозі правила;
-- відсутність застарілого `auto.md` поряд із `meta.json` (міграція метаданих у `meta.json` вже завершена).
-
-Перевірка застосовна виключно у репо самого пакета `@nitra/cursor`, де існує каталог `npm/rules/`. У споживацьких репо такого каталогу немає, тож модуль м’яко рапортує `pass` і завершується кодом виходу `0`.
-
-Модуль експортує єдину функцію `check`, яка повертає `Promise<number>` із POSIX-кодом виходу: `0` — порушень немає, `1` — є хоча б одне порушення. Звітування реалізоване через інстанс репортера, отриманий від `createCheckReporter`.
-
-## Експорти / API
-
-| Експорт                                | Тип                          | Призначення                                                                                                |
-| -------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `check(cwd?: string): Promise<number>` | іменований експорт (функція) | Валідує всі `npm/rules/<id>/meta.json` у переданому корені репозиторію та повертає підсумковий код виходу. |
-
-Інших експортів (default, типи, константи) модуль не має.
-
-## Функції
-
-### `check(cwd = process.cwd())`
-
-Валідує всі `meta.json` у `<cwd>/npm/rules/<id>/`.
-
-- **Сигнатура:** `export function check(cwd?: string): Promise<number>`
-- **Параметри:**
-  - `cwd` — рядок із абсолютним або відносним шляхом до кореня репозиторію. Необовʼязковий. Якщо не вказано, використовується `process.cwd()` (поточний робочий каталог процесу Node).
-- **Повертає:** `Promise<number>`, що резолвиться у код виходу від репортера (`reporter.getExitCode()`). Конвенція:
-  - `0` — усі знайдені правила пройшли валідацію, або каталог `npm/rules/` відсутній (у такому випадку додатково логиться `pass`-повідомлення `"npm/rules/ відсутній — немає правил для валідації"`);
-  - `1` — зафіксовано принаймні одне порушення (зокрема: залишковий `auto.md`, відсутній/невалідний `meta.json`, нерозпізнаний `auto`, невідомий `predicate`, нерозпізнаний `lint`, або `lint` без `js/lint.mjs`).
-- **Side effects:**
-  - Виконує синхронне читання файлової системи: `existsSync` для перевірки наявності `npm/rules/`, `npm/rules/<id>/auto.md`, `npm/rules/<id>/js/lint.mjs`; `readdirSync` зі списком підкаталогів `npm/rules/`.
-  - Делегує читання та парсинг `meta.json` у `readRuleMetaRaw` (також синхронне читання файла).
-  - Викликає методи репортера (`reporter.pass`, `reporter.fail`), які за домовленістю виводять статусні повідомлення (зазвичай у stdout/stderr — залежно від реалізації `createCheckReporter`).
-  - Не змінює файли на диску, не запускає дочірніх процесів, не звертається до мережі.
-- **Алгоритм:**
-  1. Створює репортер: `reporter = createCheckReporter()`.
-  2. Обчислює `rulesDir = join(cwd, 'npm', 'rules')`.
-  3. Якщо `rulesDir` не існує — рапортує `pass` і резолвить `Promise.resolve(reporter.getExitCode())` (зазвичай `0`).
-  4. Інакше перебирає вміст `rulesDir` через `readdirSync(rulesDir, { withFileTypes: true })` і для кожного запису:
-     - пропускає, якщо це не каталог (`!entry.isDirectory()`) або імʼя починається з крапки (`entry.name.startsWith('.')`);
-     - встановлює локальний прапор `ruleOk = true`;
-     - якщо знайдено залишковий `auto.md` у каталозі правила — `reporter.fail(...)`, `ruleOk = false`;
-     - читає сирий обʼєкт метаданих через `readRuleMetaRaw(ruleDir)`. Якщо повернуто falsy — `reporter.fail("rules/<id>: відсутній або невалідний meta.json")` і `continue` (наступне правило);
-     - якщо `raw.auto !== undefined` — парсить через `parseRuleAutoSpec(raw.auto)`:
-       - якщо повернуто `null` — `reporter.fail(...)`, `ruleOk = false`;
-       - інакше якщо в `spec` є ключ `'predicate'` і його значення немає у `RULE_PREDICATES` — `reporter.fail(...)`, `ruleOk = false`;
-     - якщо `raw.lint !== undefined` — валідує через `parseRuleLintPhase(raw.lint)`:
-       - якщо повернуто `null` — `reporter.fail(...)`, `ruleOk = false`;
-       - інакше якщо немає файла `<ruleDir>/js/lint.mjs` — `reporter.fail(...)`, `ruleOk = false`;
-     - наприкінці ітерації, якщо `ruleOk` усе ще `true` — `reporter.pass("rules/<id>: meta.json валідний")`.
-  5. Резолвить `Promise.resolve(reporter.getExitCode())` із підсумковим кодом виходу.
-- **Особливості реалізації:**
-  - Усі гілки порушень для одного правила фіксуються незалежно одна від одної (наприклад, у тому ж проході може бути зафіксовано і нерозпізнаний `auto`, і нерозпізнаний `lint`). Виняток — повністю відсутній/невалідний `meta.json`: тоді решта перевірок для цього правила пропускається через `continue`.
-  - Функція синхронно виконує всю роботу, але повертає `Promise<number>` через `Promise.resolve(...)` — для уніфікованої сигнатури з іншими `check`-модулями.
-  - Перевірка `'predicate' in spec` дозволяє валідувати лише гілку `{predicate}`-специфікації; інші форми (`"завжди"`, масив, `{glob}`) уже визнані валідними самим `parseRuleAutoSpec`.
-
-## Залежності
-
-### Зовнішні (Node.js standard library)
-
-- `node:fs` — `existsSync` (перевірка існування файлів і каталогів), `readdirSync` (читання вмісту каталогу `npm/rules/`).
-- `node:path` — `join` (формування шляхів до каталогів і файлів).
-
-### Внутрішні (репо-локальні)
-
-- `../../../scripts/lib/check-reporter.mjs` — `createCheckReporter()`. Створює репортер з методами `pass(msg)`, `fail(msg)`, `getExitCode()`; останній використовується для отримання підсумкового коду виходу.
-- `../../../scripts/lib/rule-meta.mjs`:
-  - `readRuleMetaRaw(ruleDir)` — читає та парсить сирий `meta.json` із каталогу правила; повертає обʼєкт або falsy (за відсутності/невалідності файла).
-  - `parseRuleAutoSpec(value)` — парсить значення поля `auto`; повертає валідовану специфікацію або `null` за нерозпізнаним вводом.
-  - `parseRuleLintPhase(value)` — парсить значення поля `lint`; повертає валідовану фазу (`"quick"`/`"ci"`) або `null`.
-- `../../../scripts/lib/rule-predicates.mjs` — `RULE_PREDICATES`: обʼєкт-реєстр відомих імен предикатів; ключі використовуються для перевірки наявності предиката через `Object.hasOwn`.
-
-### Глобальні
-
-- `process.cwd()` — використовується як дефолтний `cwd`.
-
-## Потік виконання / Використання
-
-Модуль є check-функцією конкретного правила і підпорядкований конвенції `check-{id}` (тут — `rule_meta`). Очікуваний сценарій використання:
-
-1. Виклик з вищерівневого скрипта (наприклад, агрегованої перевірки правил пакета):
-
-   ```js
-   import { check } from './npm/rules/npm-module/js/rule_meta.mjs'
-
-   const exit = await check(process.cwd())
-   process.exit(exit)
-   ```
-
-   У такому сценарії функцію викликають із кореня репозиторію пакета `@nitra/cursor`.
-
-2. Запуск у репо-споживачі (де `npm/rules/` відсутній) — функція тихо рапортує `pass` і повертає `0`, не блокуючи pipeline.
-3. Сценарій порушення: будь-який із описаних інваріантів спричиняє `fail`-звіт і код виходу `1`, що сигналізує CI зупинку.
+Перевіряє наявність директорії npm/rules у вказаному шляху. Ітерує по всіх директоріях у директорії npm/rules. Для кожної директорії виконує перевірку наявності файлу auto.md та валідність полів auto та lint у конфігурації meta.json. Перевіряє наявність файлу js/lint.mjs у каталозі правила. Збирає результати валідації та повертає код виходу репортера.
 
-Типові точки інтеграції:
+## Поведінка
 
-- CI lint-фаза пакета `@nitra/cursor` (виклик в одному з кореневих скриптів `bun run lint` / спеціалізованої перевірки правил).
-- Локальний запуск через CLI з кореня репозиторію.
+1. Перевірка наявності директорії npm/rules у вказаному шляху.
+2. Ітерація по всіх директоріях у директорії npm/rules.
+3. Для кожної директорії виконується перевірка правила.
+4. Перевірка наявності файлу auto.md у директорії правила.
+5. Перевірка валідності поля auto у meta.json правила.
+6. Перевірка наявності поля lint у meta.json правила.
+7. Перевірка валідності поля lint у meta.json правила.
+8. Перевірка наявності файлу js/lint.mjs у каталозі правила.
+9. Збір результатів валідації.
+10. Повернення коду виходу репортера.
 
-Файл не має побічних ефектів під час імпорту: експортована функція не виконується самовільно — її викликає консьюмер.
+## Публічний API
 
-## Rebuild Test
+check — Валідує всі `npm/rules/<id>/meta.json`.
 
-Контрольні питання, чиї відповіді достатні, щоб реконструювати модуль без перегляду коду:
+## Гарантії поведінки
 
-1. Який каталог сканує функція `check`?
-   - `<cwd>/npm/rules/`, де `cwd` — необовʼязковий параметр (дефолт `process.cwd()`).
-2. Як обробляється відсутність цього каталогу?
-   - Рапортується `pass("npm/rules/ відсутній — немає правил для валідації")`, повертається `0`.
-3. Які записи в `npm/rules/` пропускаються?
-   - Не-каталоги та елементи, чиє імʼя починається з `.`.
-4. За наявності якого файла поряд із `meta.json` фіксується порушення?
-   - `auto.md` (повідомлення `"rules/<id>: залишковий auto.md — видали (метадані тепер у meta.json)"`).
-5. Що відбувається, якщо `meta.json` відсутній або невалідний?
-   - `reporter.fail("rules/<id>: відсутній або невалідний meta.json")` і `continue` до наступного правила.
-6. Які гілки валідації поля `auto`?
-   - Якщо `parseRuleAutoSpec` повертає `null` — fail (нерозпізнане).
-   - Якщо специфікація містить ключ `predicate`, але його значення відсутнє в `RULE_PREDICATES` — fail (`невідомий predicate`).
-7. Які гілки валідації поля `lint`?
-   - Якщо `parseRuleLintPhase` повертає `null` — fail (`нерозпізнане, очікується "quick"|"ci"`).
-   - Якщо валідне, але немає `js/lint.mjs` — fail (`lint:"..." але немає js/lint.mjs`).
-8. Як формується підсумковий код виходу?
-   - Через `reporter.getExitCode()`, обгорнутий у `Promise.resolve(...)`.
-9. Чи синхронна реалізація?
-   - Так: усі IO операції — синхронні (`existsSync`, `readdirSync`, `readRuleMetaRaw`); проміс використано лише для уніфікації сигнатури.
-10. Які `pass`-повідомлення можливі?
-    - `"npm/rules/ відсутній — немає правил для валідації"` (за відсутності каталогу).
-    - `"rules/<id>: meta.json валідний"` (за успішної валідації окремого правила).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/rules/npm-module/js/docs/skill_meta.md

@@ -1,190 +1,28 @@
+---
+docgen:
+  source: npm/rules/npm-module/js/skill_meta.mjs
+  crc: a069397b
+  score: 100
+---
+
 # skill_meta.mjs
 
 ## Огляд
 
-Модуль `skill_meta.mjs` — перевірка валідності метаданих скілів (`meta.json`) пакета `@nitra/cursor`. Належить до концерну правила `npm-module` (тека `npm/rules/npm-module/js/`).
-
-Перевірка застосовується **виключно в репозиторії пакета**, де є каталог `npm/skills/`. Якщо каталог відсутній (наприклад, у проєктах-споживачах залежності), перевірка пропускається без помилки (повертає `pass`).
-
-Для кожного підкаталогу `npm/skills/<id>/` модуль виконує контракт:
-
-- забороняється залишковий файл `auto.md` (метадані мігровані на `meta.json`);
-- файл `meta.json` має бути присутнім і валідним JSON-об'єктом з очікуваною структурою;
-- поле `worktree` обов'язкове і має бути `boolean`;
-- поле `auto` опціональне, але якщо є — має бути або рядком `"завжди"`, або непорожнім масивом рядків.
-
-Результат акумулюється через `check-reporter` і повертається кодом виходу `0` (OK) або `1` (порушення).
-
-## Експорти / API
-
-| Експорт | Тип        | Призначення                                                                |
-| ------- | ---------- | -------------------------------------------------------------------------- |
-| `check` | `function` | Іменований експорт; функція-перевірка метаданих скілів у вказаному корені. |
-
-Модуль є ESM (`.mjs`), без `default` експорту.
-
-## Функції
-
-### `check(cwd?)`
-
-**Сигнатура:**
-
-```js
-export function check(cwd = process.cwd()): Promise<number>
-```
-
-**Параметри:**
-
-| Параметр | Тип      | Обов'язковий | За замовчуванням | Опис                                                             |
-| -------- | -------- | ------------ | ---------------- | ---------------------------------------------------------------- |
-| `cwd`    | `string` | ні           | `process.cwd()`  | Корінь репозиторію; від нього резолвиться шлях до `npm/skills/`. |
-
-**Повертає:**
-
-`Promise<number>` — код виходу від `reporter.getExitCode()`:
-
-- `0` — усі перевірені скіли валідні (або каталог `npm/skills/` відсутній);
-- `1` — щонайменше одне порушення зафіксовано через `reporter.fail(...)`.
-
-Хоча всередині немає `async`/`await`, функція обертає результат у `Promise.resolve(...)` для однорідного API з іншими `check`-функціями в цьому проєкті.
-
-**Алгоритм:**
-
-1. Створюється локальний звітник: `reporter = createCheckReporter()`.
-2. Будується шлях `skillsDir = join(cwd, 'npm', 'skills')`.
-3. Якщо `skillsDir` не існує (`existsSync(...) === false`):
-   - викликається `reporter.pass('npm/skills/ відсутній — немає скілів для валідації')`;
-   - повертається `Promise.resolve(reporter.getExitCode())` (рання гілка).
-4. Інакше — ітерація `readdirSync(skillsDir, { withFileTypes: true })`:
-   - пропускаються не-директорії та назви, що починаються з крапки (`.` префікс);
-   - для кожного скіла `id = entry.name` будується `skillDir = join(skillsDir, id)` і прапор `skillOk = true`.
-5. Для кожного скіла послідовно перевіряється:
-   - **Залишковий `auto.md`**: якщо `existsSync(join(skillDir, 'auto.md'))`, фіксується
-     `fail("skills/<id>: залишковий auto.md — видали (метадані тепер у meta.json)")` і `skillOk = false`.
-   - **`meta.json` присутній/валідний**: викликається `raw = readSkillMetaRaw(skillDir)`.
-     Якщо `raw` falsy — фіксується `fail("skills/<id>: відсутній або невалідний meta.json ...")` і виконується `continue` (решта перевірок для цього скіла пропускається).
-   - **Тип `worktree`**: якщо `typeof raw.worktree !== 'boolean'` — `fail("skills/<id>: meta.json.worktree має бути boolean")` і `skillOk = false`.
-   - **Розпізнаваність `auto`**: якщо `raw.auto !== undefined` і `parseSkillAutoSpec(raw.auto) === null` — `fail("skills/<id>: meta.json.auto нерозпізнане — очікується \"завжди\" або непорожній масив правил")` і `skillOk = false`.
-6. Якщо після всіх перевірок цього скіла `skillOk === true`, фіксується `pass("skills/<id>: meta.json валідний")`.
-7. Після проходу всіх скілів повертається `Promise.resolve(reporter.getExitCode())`.
-
-**Side effects:**
-
-- читання файлової системи (`existsSync`, `readdirSync`) — синхронне;
-- мутація стану внутрішнього звітника (`createCheckReporter()`) через `pass(...)` / `fail(...)`;
-- запис у `stdout`/`stderr` залежить від реалізації `check-reporter` (зазвичай агрегує повідомлення для подальшого виводу викликачем);
-- **не змінює** жодних файлів і **не** створює директорій.
-
-**Поведінкові інваріанти:**
-
-- Відсутність `npm/skills/` — не помилка, а явний `pass` (модуль працює і в репо-споживачі).
-- Невалідний `meta.json` зупиняє подальші перевірки конкретного скіла (`continue`), але **не зупиняє** обхід інших скілів.
-- Прихований запис (назва починається з `.`) ігнорується, тож `.DS_Store` чи `.tmp` не плутають перевірку.
-- Перевірка детермінована: результат залежить тільки від вмісту `npm/skills/` у `cwd`.
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-| Модуль      | Імпортовані символи         | Використання                                                         |
-| ----------- | --------------------------- | -------------------------------------------------------------------- |
-| `node:fs`   | `existsSync`, `readdirSync` | перевірка наявності `npm/skills/`, `auto.md`; читання списку скілів. |
-| `node:path` | `join`                      | побудова крос-платформних шляхів до каталогів і файлів.              |
-
-### Внутрішні модулі проєкту
-
-| Модуль                                    | Імпортовані символи                      | Використання                                                                |
-| ----------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
-| `../../../scripts/lib/check-reporter.mjs` | `createCheckReporter`                    | створення звітника з API `pass(msg)` / `fail(msg)` / `getExitCode()`.       |
-| `../../../scripts/lib/skill-meta.mjs`     | `readSkillMetaRaw`, `parseSkillAutoSpec` | читання сирого `meta.json` зі скіла; парсинг/валідація специфікації `auto`. |
-
-### Контракти зовнішніх модулів (як використовуються в коді)
-
-- `createCheckReporter()` → об'єкт із методами `pass(message: string)`, `fail(message: string)`, `getExitCode(): number` (`0` якщо не було `fail`, `1` якщо хоч раз був).
-- `readSkillMetaRaw(skillDir: string)` → розпарсений об'єкт `meta.json` або falsy (наприклад, `null`) якщо файл відсутній/невалідний.
-- `parseSkillAutoSpec(value)` → нормалізована специфікація `auto` або `null`, якщо значення нерозпізнане. Прийнятні форми: рядок `"завжди"` або непорожній масив рядків.
-
-## Потік виконання / Використання
-
-### Контекст
-
-Модуль викликається з раннера правил концерну `npm-module` (точка входу `npm/rules/npm-module/js/index.mjs` або аналог). У типовому пайплайні `bun run lint` / `n-cursor check` всі `check`-функції правил зібрані в реєстр і виконуються послідовно; результат об'єднується в загальний код виходу процесу.
-
-### Типовий виклик
-
-```js
-import { check } from './skill_meta.mjs'
-
-const exitCode = await check() // використає process.cwd()
-process.exit(exitCode)
-```
-
-Або з явним коренем (тести/інтеграція):
-
-```js
-const exitCode = await check('/abs/path/to/repo-root')
-```
-
-### Сценарій 1: репо самого пакета `@nitra/cursor`
-
-- `npm/skills/` існує, містить кілька скілів (наприклад, `n-docgen/`, `n-fix/`, `mdc-check/`).
-- Для кожного скіла читається `meta.json`, перевіряються `worktree` (boolean) і `auto` (опціонально).
-- Якщо хоч один скіл має `auto.md`, або відсутній/невалідний `meta.json`, або `worktree` не boolean, або `auto` нерозпізнане — функція повертає `1`.
-- Інакше — `0`.
-
-### Сценарій 2: проєкт-споживач `@nitra/cursor`
-
-- `npm/skills/` відсутній (інша файлова структура).
-- Функція фіксує `pass(...)`, повертає `0` і не виконує жодної ітерації.
-- Це дозволяє правилам пакета транзитивно застосовуватися в чужих проєктах без false-negative.
-
-### Сценарій 3: переходова міграція на `meta.json`
-
-- У скілі лишилася стара пам'ятка-метадані `auto.md` поряд з новим `meta.json`.
-- Перевірка явно фейлить такий скіл повідомленням `залишковий auto.md — видали (метадані тепер у meta.json)`.
-- Це примушує закрити технічний борг міграції.
-
-### Очікуваний формат `meta.json`
-
-```json
-{
-  "worktree": true,
-  "auto": "завжди"
-}
-```
-
-або
-
-```json
-{
-  "worktree": false,
-  "auto": ["n-bun", "n-flow"]
-}
-```
-
-або (мінімально):
+Перевірка стану конфігурації. Файл перевіряє відповідність між полями worktree та requireRoot. Перевірка спирається на конфіги meta.json.
 
-```json
-{
-  "worktree": false
-}
-```
+## Поведінка
 
-### Невалідні приклади (будуть зафейлені)
+1. Перевірка поля worktree
+2. Перевірка поля auto
+3. Перевірка поля requireRoot
+4. Перевірка суперечності between worktree та requireRoot
 
-- відсутній файл `meta.json` → `відсутній або невалідний meta.json`;
-- `{"worktree": "yes"}` → `meta.json.worktree має бути boolean`;
-- `{"worktree": true, "auto": []}` або `{"worktree": true, "auto": "always"}` → `meta.json.auto нерозпізнане ...`;
-- наявний `auto.md` поряд → `залишковий auto.md — видали`.
+## Публічний API
 
-### Rebuild Test
+check — Валідує всі `npm/skills/<id>/meta.json`.
 
-Перевірка інваріантів модуля (можна виконати вручну для регресії):
+## Гарантії поведінки
 
-1. У тимчасовому корені створити порожню директорію без `npm/skills/` → `check(tmp)` має повернути `0` і зафіксувати `pass` про відсутність каталогу.
-2. Створити `npm/skills/foo/meta.json` з валідним вмістом `{"worktree": true}` → `check(tmp)` має повернути `0`.
-3. Замінити `worktree` на рядок (`"true"`) → `check(tmp)` має повернути `1` з повідомленням про boolean.
-4. Додати `npm/skills/foo/auto.md` → `check(tmp)` має повернути `1` з повідомленням про залишковий `auto.md`.
-5. Видалити `meta.json` → `check(tmp)` має повернути `1` з повідомленням про відсутній/невалідний `meta.json`.
-6. Створити `npm/skills/.hidden/` — перевірка має ігнорувати її (повернути `0`, якщо інших скілів немає).
-7. Додати `npm/skills/bar/meta.json` з `{"worktree": false, "auto": "завжди"}` → `pass`; замінити `auto` на `"always"` → `fail` про нерозпізнане `auto`.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/rules/php/docs/fix.md

@@ -1,114 +1,37 @@
 ---
 docgen:
   source: npm/rules/php/fix.mjs
-  crc: 12fc1644
+  crc: 38cf876b
+  score: 100
 ---
 
-# fix.mjs — правило `php`
+# fix.mjs
 
 ## Огляд
 
-Файл `npm/rules/php/fix.mjs` — це точка входу правила `php` у системі `@nitra/cursor`. Він виконує дві ролі одночасно:
+Виконує застосування політики JS-занепокоєних до mdc-refs на вхідному контексті прогону та повертає результат.
 
-1. **Library mode** — експортує функцію `run(ctx)`, яку викликає CLI-оркестратор (`cursor.mjs`) під час масового прогону правил. У цьому режимі правило інтегрується у спільний pipeline і використовує загальний `walkCache` та інший контекст оркестратора.
-2. **Standalone mode** — коли файл запускається напряму через `bun rules/php/fix.mjs`, він діє як самостійний CLI-скрипт, що є повним еквівалентом команди `npx @nitra/cursor fix php` (з підтягуванням конфігурації, whitelist і фінальним summary).
+Виконується при запуску через командний рядок, виконуючи повний еквівалент команди `npx @nitra/cursor fix <id>` та повертає код виходу.
 
-Логіка правила (applies → JS-concerns → policy → mdc-refs) інкапсульована у спільному оркестраторі `runStandardRule`, тож сам файл `fix.mjs` залишається мінімальним «glue»-шаром і не містить специфічної для PHP логіки безпосередньо — конкретні чекери лежать поряд у директорії правила (`checks/`, `applies.mjs`, `policy.mjs` тощо), а їх виявлення робить `runStandardRule` за конвенцією шляху `import.meta.dirname`.
+## Поведінка
 
-## Експорти / API
+1. Запуск правила.
+    *   Приймає контекст прогону.
+    *   Виконує застосування JS-занепокоєних до політики до mdc-refs.
+    *   Повертає результат прогону.
 
-| Експорт | Тип                                            | Призначення                                                                                                                                                              |
-| ------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `run`   | `function(ctx?: RuleContext): Promise<number>` | Іменований експорт — основний entry-point library-режиму. Запускає стандартний pipeline правила в каталозі поточного модуля. Повертає exit-code (0 — OK, 1 — порушення). |
+2. Запуск у режимі CLI.
+    *   Виконується при запуску через CLI.
+    *   Виконує повний еквівалент команди `npx @nitra/cursor fix <id>`.
+    *   Повертає код виходу.
 
-Файл **не** має `default`-експорту. Side-effect на верхньому рівні модуля: блок `if (isRunAsCli(...))` із викликом `process.exit(...)` — спрацьовує лише при прямому запуску.
+## Публічний API
 
-## Функції
+run — запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+Library mode — викликається CLI orchestration через `import + run`.
 
-### `run(ctx)`
+## Гарантії поведінки
 
-```js
-export function run(ctx)
-```
-
-- **Параметри:**
-  - `ctx` _(опціональний)_ — об'єкт типу `RuleContext`, імпортований з `../../scripts/lib/run-standard-rule.mjs`. Передається оркестратором і містить кеш обходу файлової системи (`walkCache`) та інші розшаровані між правилами дані. Якщо не передано — `runStandardRule` створює власний локальний контекст.
-- **Повертає:** `Promise<number>` — exit-code прогону:
-  - `0` — правило пройшло без порушень;
-  - `1` — виявлено порушення (або правило завершилось помилкою, яку оркестратор мапить на ненульовий код).
-- **Side effects:**
-  - Делегує всю реальну роботу `runStandardRule`: читання файлів, виконання чекерів, друк summary до `stdout`/`stderr`.
-  - Сам `run` не має власних побічних ефектів — це тонкий wrapper.
-- **Як визначається корінь правила:** через `import.meta.dirname` — абсолютний шлях до директорії, в якій лежить `fix.mjs`. Це дозволяє `runStandardRule` знайти сусідні файли правила (`applies.mjs`, `policy.mjs`, `checks/*.mjs`, `*.mdc` тощо) без додаткових параметрів.
-
-## Залежності
-
-Файл імпортує дві утиліти з внутрішньої бібліотеки `npm/scripts/lib/`:
-
-| Імпорт            | Звідки                                    | Призначення                                                                                                                                                        |
-| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Детектор «чи модуль запущений напряму як CLI». Порівнює `import.meta.url` із `process.argv[1]`. Використовується для гілки standalone.                             |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Повноцінний CLI-runner правила: парсить аргументи, підтягує config, застосовує whitelist, друкує summary. Повертає `Promise<number>` із exit-кодом.                |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний pipeline правила: послідовно виконує стадії `applies → JS-concerns → policy → mdc-refs`. Приймає шлях до директорії правила та опційний `RuleContext`. |
-
-Зовнішніх npm-залежностей файл не має — лише внутрішні модулі монорепо.
-
-## Потік виконання / Використання
-
-### Сценарій A — виклик з оркестратора (library mode)
-
-1. CLI `@nitra/cursor fix` (або агрегатор) знаходить правило `php` за його директорією.
-2. Динамічно імпортує `fix.mjs` і викликає `await run(ctx)`, передаючи спільний `RuleContext` (зокрема `walkCache`, щоб уникнути повторного обходу ФС між правилами).
-3. `run` делегує виклик `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule` повертає exit-code; оркестратор агрегує коди всіх правил.
-
-```js
-import { run } from '@nitra/cursor/rules/php/fix.mjs'
-
-const code = await run(sharedCtx)
-```
-
-### Сценарій B — прямий запуск файлу (standalone mode)
-
-1. Користувач (або IDE/CI) виконує:
-   ```bash
-   bun npm/rules/php/fix.mjs
-   ```
-2. Top-level `if (isRunAsCli(import.meta.url))` повертає `true` (бо `import.meta.url` збігається з шляхом запущеного скрипта).
-3. Викликається `await runRuleCli(import.meta.dirname)` — повноцінний CLI-режим: підвантажує конфігурацію, застосовує whitelist, друкує підсумок.
-4. `process.exit(...)` завершує процес із отриманим exit-кодом, аби CI/IDE могли коректно інтерпретувати результат.
-
-### Семантика exit-кодів
-
-- `0` — правило застосовне та порушень не виявлено (або правило незастосовне для цього проєкту — `applies` повернув `false`).
-- `1` — є порушення, які треба виправити.
-
-### Коментарі та лінт-винятки
-
-У standalone-гілці явно вимкнено два правила лінтера:
-
-```js
-// eslint-disable-next-line n/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-process.exit(await runRuleCli(import.meta.dirname))
-```
-
-Це свідомий виняток: `process.exit` тут потрібний, щоб CLI/CI отримали ненульовий код у разі порушень — без нього процес міг би завершитись із кодом `0` навіть за наявності знайдених проблем.
-
-## Архітектурний контекст
-
-- **Конвенція файлу `fix.mjs`** — у директорії кожного правила (`npm/rules/<id>/fix.mjs`) лежить однотипний тонкий wrapper із двома ролями (library + standalone). Це гарантує:
-  - єдиний інтерфейс для оркестратора (`run(ctx)`);
-  - можливість запускати окреме правило ізольовано (для дебагу/CI per-rule).
-- **Чому через `import.meta.dirname`** — `runStandardRule` за директорією правила автоматично знаходить усі сусідні артефакти (`applies.mjs`, `policy.mjs`, `checks/*.mjs`, `*.mdc`). Це уникає дублювання id-правила як рядка.
-- **Patch-free wrapper** — у самому `fix.mjs` не повинно з'являтися PHP-специфічної логіки; будь-які зміни поведінки правила робляться у сусідніх файлах правила, а не в цьому entry-point'і.
-
-## Rebuild Test
-
-Файл можна повністю відтворити з опису вище за такими інваріантами:
-
-1. Два імпорти: `{ isRunAsCli, runRuleCli }` з `../../scripts/lib/run-rule-cli.mjs` і `{ runStandardRule }` з `../../scripts/lib/run-standard-rule.mjs`.
-2. Іменований експорт `function run(ctx)` — однорядкове тіло `return runStandardRule(import.meta.dirname, ctx)`.
-3. JSDoc над `run`: опис стадій (applies → JS-concerns → policy → mdc-refs), згадка library mode, тип параметра `ctx` через `import('...').RuleContext`, тип повернення `Promise<number>` із семантикою 0/1.
-4. Блок `if (isRunAsCli(import.meta.url)) { ... }` із викликом `process.exit(await runRuleCli(import.meta.dirname))` і коментарем-поясненням про дві ролі fix.mjs.
-5. Лінт-disable перед `process.exit`: `n/no-process-exit, unicorn/no-process-exit` із обґрунтуванням «standalone entry-point має повертати exit-code для CI/IDE».
-6. Жодних інших top-level операцій, жодного `default`-експорту.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.