@nitra/cursor 12.8.6 → 12.8.8

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

@@ -17,14 +17,14 @@ docgen:
 1. Перевіряє наявність каталогу `npm/skills` у поточному робочому каталозі. Якщо каталог відсутній, операція завершується успішно.
 2. Ітерує по всіх підкаталогах у `npm/skills`.
 3. Для кожного підкаталогу виконується перевірка метаданих скіла:
-    а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
-    б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
-    в. Виконується перевірка полів `main.json` скіла:
-        i. `worktree` має бути булевим значенням.
-        ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
-        iii. `requireRoot` має бути булевим значенням, якщо визначений.
-        iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
-    г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
+   а. Перевіряється наявність файлу `auto.md` у каталозі скіла. Якщо він присутній, це вважається порушенням.
+   б. Зчитується вміст `main.json` скіла. Якщо файл відсутній або невалідний, перевірка для цього скіла припиняється.
+   в. Виконується перевірка полів `main.json` скіла:
+   i. `worktree` має бути булевим значенням.
+   ii. Якщо поле `auto` визначене, його вміст має бути розпізнаним як "завжди" або непорожній масив правил.
+   iii. `requireRoot` має бути булевим значенням, якщо визначений.
+   iv. Якщо `worktree` встановлено як `true`, а `requireRoot` як `false`, це вважається порушенням.
+   г. Якщо всі поля `main.json` валідні, це вважається успішним результатом для скіла.
 4. Після перевірки всіх скілів повертається код виходу, що відображає загальний статус (0 — успіх, 1 — порушення).
 
 ## Публічний API

package/rules/npm-module/js/header_doc_pointer.mdc

@@ -0,0 +1,18 @@
+## Module-level JSDoc як pointer
+
+Якщо поряд із `js/<stem>.mjs` є файл `js/docs/<stem>.md` — module-level JSDoc у `.mjs` має бути **pointer** (не більше одного непорожнього рядка), а не повноцінний наратив.
+
+Логіка перевірки (`header_doc_pointer.mjs`):
+
+- Сканується перший JSDoc-блок (`/** … */`) до першого `import`/`export` у файлі.
+- Підраховуються непорожні рядки тіла (після зрізання `*`-відступу).
+- Якщо їх більше одного — `check` падає з повідомленням про те, що `docs/<stem>.md` вже описує поведінку і module-level JSDoc має залишатись коротким.
+
+**Покриття:** `npm/rules/*/js/*.mjs` і `npm/skills/*/js/*.mjs` (не тестові файли `*.test.mjs`). Якщо `docs/<stem>.md` відсутня — обмежень на довжину JSDoc немає.
+
+**Приклад правильного pointer-JSDoc:**
+
+```js
+/** @see ./docs/package_structure.md */
+import { existsSync } from 'node:fs'
+```

package/rules/npm-module/js/package_structure.mdc

@@ -0,0 +1,62 @@
+## Структура монорепо та компактний пакет
+
+Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
+
+Мета — **максимально компактний** опублікований пакет: у npm потрапляє тільки те, що потрібно під час `require`/`import` користувачем.
+
+- **`"files"` обовʼязковий** у `npm/package.json` як **whitelist** того, що публікується (без `"files"` npm пакує майже все — це антипатерн для цього правила).
+- **Тести й фікстури не публікуються — через негативні glob-патерни у `"files"`.** Тести можна (і зазвичай зручніше) тримати **поруч з кодом** усередині шляхів, перелічених у `"files"` (наприклад `*.test.mjs` поруч з модулем чи `fixtures/` під `rules/<id>/js/`). Щоб вони не потрапляли у tarball, `"files"` **обовʼязково має містити негативні glob-патерни**, що їх виключають. Покрий усі форми тестового: фреймворк-тести (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, …), test-style каталоги (`tests/`, `__tests__/`, `fixtures/`, `__fixtures__/`, `spec/`, `test/`), файли за патернами `*.test.*` / `*.spec.*`. Орієнтовний набір: `"!**/*.test.*"`, `"!**/*.spec.*"`, `"!**/test-helpers.*"`, `"!**/fixtures/**"`, `"!**/__tests__/**"`. **Rego (`*_test.rego`):** за конвенцією conftest юніт-тест лежить поруч з полісі у тому самому `package` — `*_test.rego` усередині опублікованого `policy/` дозволені; якщо потрібна максимальна компактність, додай `"!**/*_test.rego"` явно (як у самому `@nitra/cursor`).
+- **Лише runtime-залежності у `npm/package.json`.** `devDependencies` тримай у **кореневому** `package.json` монорепо — тоді `npm install @nitra/<pkg>` не тягне інструментарій, потрібний лише для розробки самого пакета.
+
+Перевірки JS (`package_structure.mjs`):
+- Наявність `package.json`, `npm/`, `npm/package.json`.
+- Walk шляхів з `"files"` з застосуванням негативних patterns і скан залишку на тест-патерни (walking + AST). Якщо після застосування негативних patterns у tarball лишається test-style файл — `check` падає з вказівкою, який саме негативний glob треба додати у `"files"`.
+
+## TypeScript declaration (`npm/types`)
+
+Файл **`npm/package.json`** має містити **`"types"`** (шлях до головного `.d.ts` або `.d.mts` під **`./types/…`**) і запис **`"types"`** у **`files`**, щоб npm публікував декларації.
+
+Генерація — через **`tsc`** і **`bunx -p typescript`** (окремий пакет **`typescript`** у `devDependencies` не потрібен).
+
+### Варіант A: є вихідний **`.js`** під **`npm/src/`**
+
+Якщо під **`npm/src`** (рекурсивно) є хоча б один файл **`.js`**:
+
+- **`"types": "./types/index.d.ts"`**;
+- у **hk** на **`pre-commit`** з каталогу **`npm/`** викликай:
+
+```bash
+bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types --skipLibCheck
+```
+
+Якщо glob не розгортається — **`bash -O globstar`** або **`include`** у **`tsconfig`** з тими самими **`compilerOptions`**.
+
+### Варіант B: немає **`npm/src/**/*.js`** (наприклад лише **`bin/`**, **`scripts/**/*.mjs`**)
+
+Не створюй штучний **`src/index.js`**. Замість цього:
+
+1. Додай **`npm/tsconfig.emit-types.json`** з **`include`** на реальні шляхи (`.js` / `.mjs`), **`compilerOptions`**: **`allowJs`**, **`declaration`**, **`emitDeclarationOnly`**, **`outDir`: `"types"`**, **`skipLibCheck`**: **`true`** (за потреби **`rootDir`**, **`module`**, **`moduleResolution`**).
+2. Після першого **`tsc`** подивись, який **`.d.ts`** / **`.d.mts`** відповідає публічному API, і вкажи його в **`types`** (наприклад **`./types/bin/cli.d.ts`**).
+3. У **hk** на **`pre-commit`** з **`npm/`** викликай **`tsc -p tsconfig.emit-types.json`**. Якщо через імпорти **TypeScript** все одно згенерує зайві **`.d.mts`** у **`types/`**, після **`tsc`** обрізай дерево до потрібного entrypoint (наприклад залиш лише **`types/bin/n-cursor.d.ts`** через **`find`**), щоб у пакеті не збирались декларації внутрішніх модулів.
+
+Файл **`tsconfig.emit-types.json`** тримай у репозиторії для **hk** / локальної генерації; у **`files`** його не додавай, якщо не хочеш публікувати його на **npm**.
+
+## Git hooks: hk + pre-commit
+
+У корені репозиторію — **`hk.pkl`** (або **`.config/hk.pkl`**) з **`["pre-commit"]`** і командою з відповідного варіанту (A або B) вище.
+
+Після додавання **`hk.pkl`**: **`hk install`**.
+
+## npm publish
+
+**`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
+
+Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`bunx n-cursor release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
+
+- Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
+
+## Канонічні конфіги
+
+- Кореневий `package.json` (workspaces): [package.json.snippet.json](./policy/root_package_json/template/package.json.snippet.json)
+- `npm/package.json` (whitelist `files` обовʼязково має містити `types`): [package.json.snippet.json](./policy/npm_package_json/template/package.json.snippet.json)
+- `npm/tsconfig.emit-types.json` (canonical `compilerOptions` для emit-types): [tsconfig.emit-types.json.snippet.json](./policy/emit_types_config/template/tsconfig.emit-types.json.snippet.json)

package/rules/npm-module/js/rule_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` правил
+
+Кожне правило у `npm/rules/<id>/` повинно мати коректний `main.json` (метадані правила).
+
+Перевірки (`rule_meta.mjs`):
+
+- **`main.mdc` обовʼязковий** у кожному `npm/rules/<id>/` — без нього `check` падає.
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`auto`** (опційне): `"завжди"` / масив glob-рядків / `{ glob }` / `{ predicate }`. Якщо `predicate` вказано — він має бути зареєстрований у `RULE_PREDICATES`.
+  - **`lint`** (опційне): `"per-file"` або `"full"`. Якщо вказано — `main.mjs` повинен експортувати функцію `lint` (або `export { lint } from …`).

package/rules/npm-module/js/skill_meta.mdc

@@ -0,0 +1,11 @@
+## Валідація `main.json` скілів
+
+Кожен скіл у `npm/skills/<id>/` повинен мати коректний `main.json` (метадані скіла).
+
+Перевірки (`skill_meta.mjs`):
+
+- **`auto.md` є пережитком** — якщо такий файл залишився, `check` вимагає його видалити (метадані тепер у `main.json`).
+- **`main.json` має бути валідним JSON** із коректними полями:
+  - **`worktree`** (обовʼязкове): `boolean`. Якщо `true` — скіл запускається виключно в окремому git-worktree.
+  - **`auto`** (опційне): `"завжди"` або непорожній масив ідентифікаторів правил-тригерів.
+  - **`requireRoot`** (опційне): `boolean`. Значення `false` несумісне з `worktree: true` — таку комбінацію `check` відхиляє.

package/rules/npm-module/main.mdc

@@ -7,53 +7,13 @@ version: '1.14'
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
 
-## Компактний пакет
+[npm-module-package_structure](./js/package_structure.mdc)
 
-Мета — **максимально компактний** опублікований пакет: у npm потрапляє тільки те, що потрібно під час `require`/`import` користувачем.
+[npm-module-rule_meta](./js/rule_meta.mdc)
 
-- **`"files"` обовʼязковий** у `npm/package.json` як **whitelist** того, що публікується (без `"files"` npm пакує майже все — це антипатерн для цього правила).
-- **Тести й фікстури не публікуються — через негативні glob-патерни у `"files"`.** Тести можна (і зазвичай зручніше) тримати **поруч з кодом** усередині шляхів, перелічених у `"files"` (наприклад `*.test.mjs` поруч з модулем чи `fixtures/` під `rules/<id>/js/`). Щоб вони не потрапляли у tarball, `"files"` **обовʼязково має містити негативні glob-патерни**, що їх виключають. Покрий усі форми тестового: фреймворк-тести (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, …), test-style каталоги (`tests/`, `__tests__/`, `fixtures/`, `__fixtures__/`, `spec/`, `test/`), файли за патернами `*.test.*` / `*.spec.*`. Орієнтовний набір: `"!**/*.test.*"`, `"!**/*.spec.*"`, `"!**/test-helpers.*"`, `"!**/fixtures/**"`, `"!**/__tests__/**"`. **Rego (`*_test.rego`):** за конвенцією conftest юніт-тест лежить поруч з полісі у тому самому `package` — `*_test.rego` усередині опублікованого `policy/` дозволені; якщо потрібна максимальна компактність, додай `"!**/*_test.rego"` явно (як у самому `@nitra/cursor`).
-- **Лише runtime-залежності у `npm/package.json`.** `devDependencies` тримай у **кореневому** `package.json` монорепо — тоді `npm install @nitra/<pkg>` не тягне інструментарій, потрібний лише для розробки самого пакета.
+[npm-module-skill_meta](./js/skill_meta.mdc)
 
-Деталі алгоритму перевірки:
-
-- Пер-документні правила для `npm/package.json` (whitelist `files`, заборона `devDependencies`, форма `types`) — у rego-пакеті `npm_module.npm_package_json` (`npm/policy/npm_module/npm_package_json/`).
-- Walk шляхів з `"files"` з застосуванням негативних patterns і скан залишку на тест-патерни (walking + AST JS/TS) — у `check.mjs::checkNoTestsInPublishedFiles` (FS / AST не лягають у rego). Якщо після застосування негативних patterns у tarball лишається test-style файл — `check` падає з вказівкою, який саме негативний glob треба додати у `"files"`.
-
-## TypeScript declaration (`npm/types`)
-
-Файл **`npm/package.json`** має містити **`"types"`** (шлях до головного `.d.ts` або `.d.mts` під **`./types/…`**) і запис **`"types"`** у **`files`**, щоб npm публікував декларації.
-
-Генерація — через **`tsc`** і **`bunx -p typescript`** (окремий пакет **`typescript`** у `devDependencies` не потрібен).
-
-### Варіант A: є вихідний **`.js`** під **`npm/src/`**
-
-Якщо під **`npm/src`** (рекурсивно) є хоча б один файл **`.js`**:
-
-- **`"types": "./types/index.d.ts"`**;
-- у **hk** на **`pre-commit`** з каталогу **`npm/`** викликай:
-
-```bash
-bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types --skipLibCheck
-```
-
-Якщо glob не розгортається — **`bash -O globstar`** або **`include`** у **`tsconfig`** з тими самими **`compilerOptions`**.
-
-### Варіант B: немає **`npm/src/**/*.js`** (наприклад лише **`bin/`**, **`scripts/**/*.mjs`**)
-
-Не створюй штучний **`src/index.js`**. Замість цього:
-
-1. Додай **`npm/tsconfig.emit-types.json`** з **`include`** на реальні шляхи (`.js` / `.mjs`), **`compilerOptions`**: **`allowJs`**, **`declaration`**, **`emitDeclarationOnly`**, **`outDir`: `"types"`**, **`skipLibCheck`**: **`true`** (за потреби **`rootDir`**, **`module`**, **`moduleResolution`**).
-2. Після першого **`tsc`** подивись, який **`.d.ts`** / **`.d.mts`** відповідає публічному API, і вкажи його в **`types`** (наприклад **`./types/bin/cli.d.ts`**).
-3. У **hk** на **`pre-commit`** з **`npm/`** викликай **`tsc -p tsconfig.emit-types.json`**. Якщо через імпорти **TypeScript** все одно згенерує зайві **`.d.mts`** у **`types/`**, після **`tsc`** обрізай дерево до потрібного entrypoint (наприклад залиш лише **`types/bin/n-cursor.d.ts`** через **`find`**), щоб у пакеті не збирались декларації внутрішніх модулів.
-
-Файл **`tsconfig.emit-types.json`** тримай у репозиторії для **hk** / локальної генерації; у **`files`** його не додавай, якщо не хочеш публікувати його на **npm**.
-
-## Git hooks: hk + pre-commit
-
-У корені репозиторію — **`hk.pkl`** (або **`.config/hk.pkl`**) з **`["pre-commit"]`** і командою з відповідного варіанту (A або B) вище.
-
-Після додавання **`hk.pkl`**: **`hk install`**.
+[npm-module-header_doc_pointer](./js/header_doc_pointer.mdc)
 
 ## Версія та CHANGELOG
 
@@ -61,16 +21,14 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 Повна модель (база порівняння, інверсія шляхів, формат CHANGELOG, post-release-інваріант «верхня секція CHANGELOG == `version`») — у **`n-changelog.mdc`** (джерело істини). Це правило їй підпорядковане й власних інструкцій bump/CHANGELOG не дублює.
 
-## npm publish
+## Швидкий gate через conftest
 
-**`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
+Rego-пакети (запускаються через `npx @nitra/cursor fix`):
 
-Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`bunx n-cursor release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
+[npm-module-npm_package_json](./policy/npm_package_json/npm_package_json.mdc)
 
-- Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
+[npm-module-root_package_json](./policy/root_package_json/root_package_json.mdc)
 
-## Канонічні конфіги
+[npm-module-emit_types_config](./policy/emit_types_config/emit_types_config.mdc)
 
-- Кореневий `package.json` (workspaces): [package.json.snippet.json](./policy/root_package_json/template/package.json.snippet.json)
-- `npm/package.json` (whitelist `files` обовʼязково має містити `types`): [package.json.snippet.json](./policy/npm_package_json/template/package.json.snippet.json)
-- `npm/tsconfig.emit-types.json` (canonical `compilerOptions` для emit-types): [tsconfig.emit-types.json.snippet.json](./policy/emit_types_config/template/tsconfig.emit-types.json.snippet.json)
+- `npm_module.npm_publish_yml` — template-driven перевірка `.github/workflows/npm-publish.yml` (deep-subset: усі обовʼязкові поля й кроки з канонічного сніпету).

package/rules/npm-module/policy/emit_types_config/emit_types_config.mdc

@@ -0,0 +1,40 @@
+## Rego-gate: конфігурація генерації типів `npm/tsconfig.emit-types.json`
+
+Rego-пакет: `npm-module.emit_types_config`
+
+Цільовий файл: `npm/tsconfig.emit-types.json`
+
+### Що перевіряється
+
+Leaf-by-leaf порівняння з канонічним сніпетом (через `--data`): кожне поле всередині `compilerOptions` має точно відповідати очікуваному значенню. Якщо секція `compilerOptions` відсутня або не є обʼєктом — окрема deny-помилка.
+
+Канонічний сніпет: [tsconfig.emit-types.json.snippet.json](./template/tsconfig.emit-types.json.snippet.json)
+
+### Допустимі відхилення
+
+Додаткові поля у `compilerOptions` (наприклад `rootDir`, `baseUrl`) не спричиняють помилку — перевіряється лише наявність і коректність обовʼязкових ключів зі сніпету.
+
+### Приклади
+
+✓ Правильно:
+```json
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "types",
+    "skipLibCheck": true
+  }
+}
+```
+
+✗ Неправильно — неправильний `outDir`:
+```json
+{ "compilerOptions": { "outDir": "dist" } }
+```
+
+✗ Неправильно — відсутній `compilerOptions`:
+```json
+{}
+```

package/rules/npm-module/policy/npm_package_json/npm_package_json.mdc

@@ -0,0 +1,50 @@
+## Rego-gate: валідація `npm/package.json`
+
+Rego-пакет: `npm-module.npm_package_json`
+
+Цільовий файл: `npm/package.json`
+
+### Що перевіряється
+
+**Поле `types`** (логіка в rego, не template-driven):
+- Має відповідати патерну `./types/index.d.ts` або `./types/<назва>.d.ts|.d.mts`.
+- Шляхи поза директорією `types/` або з іншими розширеннями (`.ts` без `.d`) — deny.
+
+**Поле `files`** (частково template-driven):
+- Обовʼязкове, має бути непорожнім масивом.
+- Subset-of перевірка: кожне значення з канонічного сніпету має бути присутнє у `files`. За замовчуванням — `"types"` обовʼязковий.
+
+**Поле `devDependencies`** (inverse-pattern, логіка в rego):
+- Не публікуються користувачам пакета — має бути відсутнє або порожнє `{}`.
+- Наявність будь-яких devDeps → deny з переліком залежностей. Перенести у кореневий `package.json`.
+
+Канонічний сніпет `files`: [package.json.snippet.json](./template/package.json.snippet.json)
+
+FS-перевірки (наявність файлу зі шляху `types`, скан tarball на тест-патерни) — у JS-перевірці, не тут.
+
+### Приклади
+
+✓ Правильно:
+```json
+{
+  "name": "@nitra/cursor",
+  "types": "./types/bin/n-cursor.d.ts",
+  "files": ["types", "mdc", "bin", "CHANGELOG.md"],
+  "dependencies": { "oxc-parser": "^0.128.0" }
+}
+```
+
+✗ Неправильно — `types` поза директорією `types/`:
+```json
+{ "types": "./dist/index.d.ts" }
+```
+
+✗ Неправильно — `files` без `"types"`:
+```json
+{ "files": ["bin", "mdc"] }
+```
+
+✗ Неправильно — наявні `devDependencies`:
+```json
+{ "devDependencies": { "@nitra/cursor": "^1.0.0" } }
+```

package/rules/npm-module/policy/root_package_json/root_package_json.mdc

@@ -0,0 +1,37 @@
+## Rego-gate: валідація кореневого `package.json`
+
+Rego-пакет: `npm-module.root_package_json`
+
+Цільовий файл: `package.json` (корінь репозиторію)
+
+### Що перевіряється
+
+Subset-of перевірка масиву `workspaces`: кожне значення з канонічного сніпету має бути присутнє у `workspaces`. За замовчуванням обовʼязковий елемент — `"npm"`.
+
+Якщо `workspaces` відсутнє або не є масивом — окрема deny-помилка.
+
+Канонічний сніпет: [package.json.snippet.json](./template/package.json.snippet.json)
+
+Решта перевірок кореневого `package.json` (заборонені поля, devDeps лише `@nitra/*`) — у пакеті `bun.package_json`. FS-перевірки (наявність директорії `npm/`, `npm/package.json`) — у JS.
+
+### Приклади
+
+✓ Правильно — `workspaces` містить `"npm"`:
+```json
+{ "workspaces": ["npm"] }
+```
+
+✓ Правильно — `workspaces` містить `"npm"` разом з іншими:
+```json
+{ "workspaces": ["demo", "npm", "tests"] }
+```
+
+✗ Неправильно — `workspaces` відсутній:
+```json
+{ "name": "monorepo" }
+```
+
+✗ Неправильно — `workspaces` без `"npm"`:
+```json
+{ "workspaces": ["demo"] }
+```

package/rules/php/js/lint_php_yml.mdc

@@ -0,0 +1,12 @@
+## CI: `.github/workflows/lint-php.yml`
+
+Канон workflow — [lint-php.yml.snippet.yml](./policy/lint_php_yml/template/lint-php.yml.snippet.yml).
+
+Файл запускається при push/PR до `dev`/`main` за змінами в `**/*.php`, `composer.json`, `composer.lock`, `phpstan.neon`, `phpstan.neon.dist`, `psalm.xml` або самого workflow.
+
+Кроки job `php`:
+1. `actions/checkout@v6` (без persist-credentials)
+2. `./.github/actions/setup-bun-deps`
+3. `shivammathur/setup-php@v2` — PHP 8.5
+4. `composer install --no-interaction --no-progress --prefer-dist`
+5. `n-cursor lint php --read-only`

package/rules/php/js/tooling.mdc

@@ -0,0 +1,66 @@
+## PHP-інструменти лінту
+
+Весь код повинен відповідати PHP 8.5, перевірятися через PHPCompatibility і конвертуватися через Rector.
+
+Код має бути добре задокументований через phpDoc:
+
+```php
+/** @param array<int, string> $items */
+function process($items) {
+    foreach ($items as $id => $name) {
+        // PHPStan знає, що $id — int, $name — string
+    }
+}
+```
+
+### PHP_CodeSniffer (phpcs) і пакет `squizlabs/php_codesniffer`
+
+Стиль, базові ризики, за потреби окремі стандарти. Для **SQL injection**, **XSS**, **небезпечні функції** — PHPCS + **php-security-audit** (стандарт `Security`).
+
+```bash
+phpcs --standard=Security app/
+```
+
+### PHPStan
+
+Статичний аналіз типів і смертельних слабких місць; **PHPStan Taint Analysis** (`phpstan/phpstan-taint-analysis`) — для потоку даних (taint) у стилі security-аналізу.
+
+```bash
+vendor/bin/phpstan analyse
+# після підключення розширення taint — у phpstan.neon/ neon.dist
+```
+
+### PHP-CS-Fixer
+
+Форматтер/фіксер коду; у **lint** зазвичай перевірка без змін (`--dry-run`).
+
+```bash
+vendor/bin/php-cs-fixer fix --dry-run --diff
+```
+
+### Psalm
+
+Альтернативний/додатковий аналізатор; **Psalm Security Plugin** (`vimeo/psalm` + пакет на кшталт `psalm/plugin-security` залежно від вибраної збірки) — для security-орієнтованих правил.
+
+```bash
+vendor/bin/psalm
+```
+
+### `composer audit`
+
+Перевірка відомих вразливостей залежностей за даними **Packagist/security-advisories**.
+
+```bash
+composer audit
+```
+
+## Запуск lint-php
+
+`composer`-інструменти не мають єдиного CLI, який сам обходить репозиторій, тому php-лінт делегується у JS-скрипт-обгортку. Запуск — через **`n-cursor lint php`** (CI — `--read-only`); окремого `package.json`-скрипта немає.
+
+Скрипт `run-php.mjs`:
+
+- якщо `composer.json` у корені відсутній — вихід 0 (перевірка пропущена);
+- якщо `composer.json` є, але `composer` не знайдено в PATH — це помилка;
+- `composer audit` — обовʼязковий;
+- `vendor/bin/php-cs-fixer`, `vendor/bin/phpcs`, `vendor/bin/phpstan`, `vendor/bin/psalm` — запускаються лише якщо встановлені (інакше крок пропускається з повідомленням).

package/rules/php/main.mdc

@@ -5,73 +5,12 @@ globs: "**/*.php"
 alwaysApply: false
 ---
 
-Весь код повинен відповідати PHP 8.5, перевіряти за допомогою PHPCompatibility, конвертувати за допомогою Rector.
+Весь код повинен відповідати PHP 8.5 (PHPCompatibility + Rector). Лінт запускається через `n-cursor lint php`.
 
-Код повинен бути добре документований за допомогою phpDoc-ів:
+[php-tooling](./js/tooling.mdc)
 
-```php
-/** @param array<int, string> $items */
-function process($items) {
-    foreach ($items as $id => $name) {
-        // PHPStan знає, що $id — int, $name — string
-    }
-}
-```
+[php-lint_php_yml](./js/lint_php_yml.mdc)
 
-## Потрібно додати до lint-php
+## Швидкий gate через conftest
 
-### PHP_CodeSniffer (phpcs) і пакет `squizlabs/php_codesniffer`
-
-Стиль, базові ризики, за потреби окремі стандарти. Для **SQL injection**, **XSS**, **небезпечні функції** — PHPCS + **php-security-audit** (стандарт `Security`).
-
-```bash
-phpcs --standard=Security app/
-```
-
-### PHPStan
-
-Статичний аналіз типів і смертельних слабких місць; **PHPStan Taint Analysis** (`phpstan/phpstan-taint-analysis`) — для потоку даних (taint) у стилі security-аналізу.
-
-```bash
-vendor/bin/phpstan analyse
-# після підключення розширення taint — у phpstan.neon/ neon.dist
-```
-
-### PHP-CS-Fixer
-
-Форматтер/фіксер коду; у **lint** зазвичай перевірка без змін (`--dry-run`).
-
-```bash
-vendor/bin/php-cs-fixer fix --dry-run --diff
-```
-
-### Psalm
-
-Альтернативний/додатковий аналізатор; **Psalm Security Plugin** (`vimeo/psalm` + пакет на кшталт `psalm/plugin-security` залежно від вибраної збірки) — для security-орієнтованих правил.
-
-```bash
-vendor/bin/psalm
-```
-
-### `composer audit`
-
-Перевірка відомих вразливостей залежностей за даними **Packagist/security-advisories**.
-
-```bash
-composer audit
-```
-
-## lint-php
-
-`composer`-інструмененти не мають єдиного CLI, який сам обходить репозиторій, тому php-лінт делегується у JS-скрипт-обгортку. Запуск — через **`n-cursor lint php`** (CI — `--read-only`); окремого `package.json`-скрипта немає.
-
-Скрипт `run-php.mjs`:
-
-- якщо `composer.json` у корені відсутній — вихід 0 (перевірка пропущена);
-- якщо `composer.json` є, але `composer` не знайдено в PATH — це помилка;
-- `composer audit` — обовʼязковий;
-- `vendor/bin/php-cs-fixer`, `vendor/bin/phpcs`, `vendor/bin/phpstan`, `vendor/bin/psalm` — запускаються лише якщо встановлені (інакше крок пропускається з повідомленням).
-
-## CI: `.github/workflows/lint-php.yml`
-
-- Канон: [lint-php.yml.snippet.yml](./policy/lint_php_yml/template/lint-php.yml.snippet.yml)
+[php-lint_php_yml](./policy/lint_php_yml/lint_php_yml.mdc)

package/rules/php/policy/lint_php_yml/lint_php_yml.mdc

@@ -0,0 +1,21 @@
+## Структура `.github/workflows/lint-php.yml`
+
+Rego-пакет: `php.lint_php_yml`
+
+Цільовий файл: `.github/workflows/lint-php.yml` (парситься як YAML).
+
+Перевіряє, що у workflow присутні всі канонічні `run:`-кроки з template-сніпету — крок `n-cursor lint php --read-only` має бути в одному зі steps jobs.
+
+Канонічний template-сніпет: [lint-php.yml.snippet.yml](./template/lint-php.yml.snippet.yml)
+
+**✓ Правильно** — job `php` містить крок:
+```yaml
+- name: Lint PHP
+  run: n-cursor lint php --read-only
+```
+
+**✗ Неправильно** — крок відсутній або містить інший run-рядок:
+```yaml
+- name: Lint PHP
+  run: echo something
+```

package/rules/python/js/lint_python_yml.mdc

@@ -0,0 +1,23 @@
+## CI: `.github/workflows/lint-python.yml`
+
+Канонічний workflow: [lint-python.yml.snippet.yml](./policy/lint_python_yml/template/lint-python.yml.snippet.yml)
+
+Без кроків `poetry install` / `snok/install-poetry` — лише `astral-sh/setup-uv@v8.0.0` + `uv sync --frozen`.
+
+Обовʼязкові кроки:
+- `actions/checkout@v6` з `persist-credentials: false`;
+- `./.github/actions/setup-bun-deps` — встановлення JS-залежностей (для `n-cursor lint`);
+- `astral-sh/setup-uv@v8.0.0` — встановлення uv;
+- `uv sync --frozen` — встановлення Python-залежностей строго з lock-файлу;
+- `n-cursor lint python --read-only` — запуск lint (без auto-fix у CI).
+
+`uv` / `ruff` / `mypy` **не** додаються в кореневі `devDependencies` споживача — це окремий toolchain, що ставиться через `astral-sh/setup-uv` у CI або локально.
+
+## Rego: python.lint_python_yml
+
+Polісі `policy/lint_python_yml/lint_python_yml.rego` — drift-safe перевірка через `--data template`:
+
+- кожен `uses` з template має бути присутнім у workflow input;
+- кожен `run` з template має бути substring серед run-кроків input.
+
+Заборона Poetry-кроків (`snok/install-poetry`, `poetry install`) забезпечується відсутністю у каноні: правило вимагає uv-кроки, і жодних poetry-кроків у template немає.

package/rules/python/js/pyproject_toml.mdc

@@ -0,0 +1,32 @@
+## pyproject.toml: PEP 621 і заборона Poetry
+
+Метадані проєкту — у секції **`[project]`** (PEP 621), а **не** в `[tool.poetry]`.
+
+Обовʼязкові поля:
+- `[project].name` — назва пакета;
+- `[project].version` — статична версія;
+- `[project].requires-python` — мінімальна версія Python;
+- `[project].dependencies` — залежності (навіть порожній список).
+
+Lock-файл — **`uv.lock`** (коммітиться). `poetry.lock` / `poetry.toml` мають бути відсутні.
+
+Залежності: `uv add <pkg>`; dev-залежності: `uv add --dev <pkg>`.
+
+Канонічний цільовий вигляд `pyproject.toml`: [pyproject.toml.snippet.toml](./policy/pyproject_toml/template/pyproject.toml.snippet.toml)
+
+Заборонені під-таблиці `[tool.*]` (Poetry): [pyproject.toml.deny.toml](./policy/pyproject_toml/template/pyproject.toml.deny.toml)
+
+## Міграція з Poetry на uv
+
+1. Прибери `[tool.poetry]` і `poetry.lock` / `poetry.toml`.
+2. Перенеси метадані в `[project]` (name, version, requires-python, dependencies) за PEP 621.
+3. Згенеруй lock: `uv lock` → `uv.lock`.
+4. Dev-залежності: `uv add --dev ruff mypy …`.
+
+## Rego: python.pyproject_toml
+
+Polисі `policy/pyproject_toml/pyproject_toml.rego` — дві групи правил:
+
+**1. Заборона Poetry** — перевіряє, чи є заборонені під-таблиці `[tool.*]` з `pyproject.toml.deny.toml` (drift-safe через `--data template`).
+
+**2. PEP 621** — `[project].name` і `[project].version` мають бути непорожніми рядками.

package/rules/python/js/tooling.mdc

@@ -0,0 +1,23 @@
+## Перевірка наявності uv-toolchain і відсутності Poetry
+
+JS-перевірка (`js/tooling.mjs`) запускається, якщо в корені репо є `pyproject.toml`. Перевіряє:
+
+- `uv.lock` — має існувати (зафіксувати командою `uv lock`);
+- `poetry.lock` / `poetry.toml` — мають **бути відсутніми** (Poetry заборонено);
+- `package.json` — має бути у корені (js-обгортка lint є частиною монорепо);
+- `.github/workflows/lint-python.yml` — має існувати (структуру перевіряє Rego-полісі `python.lint_python_yml`).
+
+Якщо `pyproject.toml` відсутній — перевірка пропускається з кодом 0 (проєкт не Python).
+
+## lint-python: JS-скрипт-обгортка
+
+Інструменти uv-екосистеми не мають єдиного CLI-обходу репо, тому python-лінт делегується у JS-скрипт-обгортку. Запуск — через **`n-cursor lint python`** (CI — `--read-only`); окремого `package.json`-скрипта немає.
+
+Скрипт `rules/python/lint/lint.mjs`:
+
+- якщо `pyproject.toml` у корені відсутній — вихід 0 (перевірка пропущена);
+- якщо `pyproject.toml` є, але `uv` не знайдено в PATH — це помилка;
+- `uv lock --check` і `uv sync --frozen` — обовʼязкові;
+- `uv run ruff check --fix .` + `uv run ruff format .` — auto-fix (мутують робоче дерево, як `markdownlint-cli2 --fix` у lint-text);
+- `uv run mypy .` — статична перевірка типів;
+- усі `ruff`/`mypy`-кроки запускаються лише якщо інструмент доступний у середовищі (інакше крок пропускається з повідомленням).