@7n/rules-lang-js 0.3.1 → 0.4.1

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

@@ -0,0 +1,63 @@
+## Структура монорепо та компактний пакет
+
+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"` явно (як у самому `@7n/rules`).
+- **Лише 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-rules.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-rules 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-rules 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/root_package_json/concern.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "policy": {
+    "files": {
+      "single": "package.json"
+    }
+  }
+}

package/rules/npm-module/root_package_json/docs/fix-root_package_json.md

@@ -0,0 +1,25 @@
+---
+type: JS Module
+title: fix-root_package_json.mjs
+resource: plugins/lang-js/rules/npm-module/root_package_json/fix-root_package_json.mjs
+docgen:
+  crc: 7b0c2f93
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`patterns` перевіряє кореневий `package.json` на відповідність еталонному шаблону npm-module і використовується для контролю очікуваної структури цього конфіга. Публічна функція: `patterns`. Конфіг, на який спирається код: `package.json`.
+
+## Поведінка
+
+1. `patterns` визначає набір правил, які звіряють кореневий `package.json` з еталонним шаблоном для npm-module.
+2. Кожне правило в цьому наборі націлене на `package.json` і використовується для вирівнювання кореневого конфіга з очікуваною структурою проєкту.
+3. `patterns` потрібен, щоб централізовано підтримувати однаковий формат root `package.json` у межах цього типу пакета.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/root_package_json/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/npm-module/root_package_json
+resource: plugins/lang-js/rules/npm-module/root_package_json/
+---
+
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [fix-root_package_json.mjs](fix-root_package_json.md) | JS Module |

package/rules/npm-module/root_package_json/fix-root_package_json.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '@7n/rules/scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'npm-module-root_package_json-template', targetPath: 'package.json' })
+]

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

@@ -0,0 +1,41 @@
+## 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/npm-module/root_package_json/root_package_json.rego

@@ -0,0 +1,28 @@
+# Перевірка кореневого `package.json` для npm-module (npm-module.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/package.json.snippet.json.
+# Snippet-array subset-of: кожне значення з template-масиву має бути у input-масиві.
+# Решта кореневих `package.json`-перевірок (заборонені поля, devDeps лише @nitra/*)
+# — у `bun.package_json`. FS-перевірки (наявність каталогу `npm/`, `npm/package.json`)
+# — у JS.
+package npm_module.root_package_json
+
+import rego.v1
+
+# Поле має бути масивом — інакше окрема deny.
+deny contains msg if {
+	some field in object.keys(data.template.snippet)
+	not is_array(object.get(input, field, null))
+	msg := sprintf("package.json: масив %s відсутній або не масив (npm-module.mdc)", [field])
+}
+
+# Subset-of: кожне значення з template має бути в input-масиві.
+deny contains msg if {
+	some field, expected_values in data.template.snippet
+	is_array(object.get(input, field, null))
+	actual_set := {v | some v in input[field]}
+	some required in expected_values
+	not required in actual_set
+	msg := sprintf("package.json: %s має містити %q (npm-module.mdc)", [field, required])
+}

package/rules/npm-module/root_package_json/template/package.json.snippet.json

@@ -0,0 +1 @@
+{ "workspaces": ["npm"] }

package/rules/npm-module/rule_meta/concern.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": {
+    "scope": "full",
+    "glob": ["npm/rules/**/main.json", "npm/rules/**/main.mjs", "npm/rules/**/main.mdc", "npm/rules/**/auto.md"]
+  }
+}

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

@@ -0,0 +1,35 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/npm-module/rule_meta/main.mjs
+docgen:
+  crc: c7424bda
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
+  issues: anchor-miss:(scripts.mdc),judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Lint-детектор concern-а `npm-module/rule_meta`: валідує метадані кожного правила у `npm/rules/<id>/` — файл `main.json` та супутні конвенції каталогу правила.
+
+## Поведінка
+
+1. Якщо `npm/rules/` відсутній — pass (немає правил для валідації).
+2. Для кожної теки правила:
+   - `auto.md` є пережитком — якщо файл лишився, порушення (метадані тепер у `main.json`).
+   - `main.mdc` обовʼязковий (канон scripts.mdc) — відсутність = порушення.
+   - `main.json` має існувати і бути валідним JSON-обʼєктом.
+   - Поле `auto` (опційне) має відповідати одній з форм: `"завжди"` / масив / `{ glob }` / `{ predicate }`; предикат має бути зареєстрований у `RULE_PREDICATES`.
+   - Поле `lint` заборонене: rule-level lint-scope скасовано (spec 2026-06-28-concern-lint-scope-design) — lint-поверхня декларується у `<rule>/<concern>/concern.json#lint`.
+   - Поле `llmFix` заборонене: opt-in-прапорця немає — fix-можливість концерну визначається наявністю `fix-*.mjs`/`fix-worker.mjs`.
+3. Повертає `LintResult` зі списком порушень; валідні правила репортяться як pass.
+
+## Публічний API
+
+lint — перевіряє `main.json` усіх правил у `npm/rules/` і повертає `{ violations }`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/rule_meta/main.mjs

@@ -0,0 +1,119 @@
+/** @see ./docs/main.md */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { parseRuleAutoSpec, readRuleMetaRaw } from '@7n/rules/scripts/lib/rule-meta.mjs'
+import { RULE_PREDICATES } from '@7n/rules/scripts/lib/rule-predicates.mjs'
+
+/**
+ * Перевіряє поле `auto` у meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле валідне (або відсутнє)
+ */
+function checkAutoField(id, raw, reporter) {
+  if (raw.auto === undefined) return true
+  const spec = parseRuleAutoSpec(raw.auto)
+  if (spec === null) {
+    const autoHint = 'нерозпізнане (очікується "завжди" / масив / {glob} / {predicate})'
+    reporter.fail(`rules/${id}: main.json.auto ${autoHint}`)
+    return false
+  }
+  if ('predicate' in spec && !Object.hasOwn(RULE_PREDICATES, spec.predicate)) {
+    reporter.fail(`rules/${id}: main.json — невідомий predicate "${spec.predicate}" (немає в RULE_PREDICATES)`)
+    return false
+  }
+  return true
+}
+
+/**
+ * Забороняє залишкове поле `lint` у meta.json правила.
+ * Канон (spec 2026-06-28-concern-lint-scope-design): lint-scope живе у
+ * `<rule>/<concern>/concern.json#lint`, rule-level `main.json.lint` скасовано.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле відсутнє
+ */
+function checkLintField(id, raw, reporter) {
+  if (raw.lint === undefined) return true
+  reporter.fail(`rules/${id}: main.json.lint скасовано — lint-scope декларується у <concern>/concern.json#lint`)
+  return false
+}
+
+/**
+ * Забороняє залишкове поле `llmFix` у meta.json правила.
+ * Канон (scripts.mdc, spec 2026-06-28-concern-lint-scope-design): opt-in-прапорця
+ * llmFix немає — fix-можливість концерну визначається наявністю `fix-*.mjs`/`fix-worker.mjs`.
+ * @param {string} id ідентифікатор правила
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо поле відсутнє
+ */
+function checkLlmFixField(id, raw, reporter) {
+  if (raw.llmFix === undefined) return true
+  reporter.fail(
+    `rules/${id}: main.json.llmFix скасовано — fix-можливість = наявність fix-*.mjs/fix-worker.mjs у концерні`
+  )
+  return false
+}
+
+/**
+ * Валідує meta.json одного правила.
+ * @param {string} id ідентифікатор правила
+ * @param {string} ruleDir каталог правила
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkRule(id, ruleDir, reporter) {
+  let ruleOk = true
+
+  if (existsSync(join(ruleDir, 'auto.md'))) {
+    reporter.fail(`rules/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
+    ruleOk = false
+  }
+
+  // Канон (scripts.mdc): main.mdc — ОБОВ'ЯЗКОВИЙ у кожному npm/rules/<id>/.
+  if (!existsSync(join(ruleDir, 'main.mdc'))) {
+    reporter.fail(`rules/${id}: відсутній main.mdc — обов'язковий (scripts.mdc)`)
+    ruleOk = false
+  }
+
+  const raw = readRuleMetaRaw(ruleDir)
+  if (!raw) {
+    reporter.fail(`rules/${id}: відсутній або невалідний main.json`)
+    return
+  }
+
+  if (!checkAutoField(id, raw, reporter)) ruleOk = false
+  if (!checkLintField(id, raw, reporter)) ruleOk = false
+  if (!checkLlmFixField(id, raw, reporter)) ruleOk = false
+
+  if (ruleOk) {
+    reporter.pass(`rules/${id}: main.json валідний`)
+  }
+}
+
+/**
+ * Валідує всі `npm/rules/<id>/meta.json`.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx Контекст лінту (`cwd` тощо).
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} Результат лінту зі списком violations.
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const rulesDir = join(cwd, 'npm', 'rules')
+  if (!existsSync(rulesDir)) {
+    reporter.pass('npm/rules/ відсутній — немає правил для валідації')
+    return Promise.resolve(reporter.result())
+  }
+
+  for (const entry of readdirSync(rulesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    checkRule(entry.name, join(rulesDir, entry.name), reporter)
+  }
+
+  return Promise.resolve(reporter.result())
+}

package/rules/npm-module/rule_meta/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` заборонене**: rule-level scope скасовано — lint-поверхня декларується per-concern у `<rule>/<concern>/concern.json#lint` (spec 2026-06-28-concern-lint-scope-design).

package/rules/npm-module/skill_meta/concern.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "config",
+  "lint": { "scope": "full", "glob": ["npm/skills/**/main.json", "npm/skills/**/auto.md"] }
+}

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

@@ -0,0 +1,149 @@
+---
+type: JS Module
+title: main.mjs
+resource: plugins/lang-js/rules/npm-module/skill_meta/main.mjs
+docgen:
+  crc: 1bfaac0d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+system_message:
+You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+(none)
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+
+- Be concise in your responses
+- Show file paths clearly when working with files
+
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+
+- Main documentation: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/README.md
+- Additional docs: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/docs
+- Examples: /Users/vitalii/www/nitra/cursor/node_modules/@earendil-works/pi-coding-agent/examples (extensions, custom tools, SDK)
+- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the pi .md files completely and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)
+
+<project_context>
+Project-specific instructions and guidelines:
+
+<project_instructions path="/Users/vitalii/www/nitra/cursor/AGENTS.md">
+
+# AGENTS.md version: '1.0'
+
+## Purpose
+
+This file is the entry point for all AI agents working with this repository.
+
+## Rule source
+
+The primary development rules are stored in the Cursor rules directory:
+
+- .cursor/rules/conftest.mdc
+- .cursor/rules/dev-dep.mdc
+- .cursor/rules/n-adr.mdc
+- .cursor/rules/n-bun.mdc
+- .cursor/rules/n-changelog.mdc
+- .cursor/rules/n-ci4.mdc
+- .cursor/rules/n-doc-files.mdc
+- .cursor/rules/n-feedback.mdc
+- .cursor/rules/n-ga.mdc
+- .cursor/rules/n-js-run.mdc
+- .cursor/rules/n-js.mdc
+- .cursor/rules/n-npm-module.mdc
+- .cursor/rules/n-python.mdc
+- .cursor/rules/n-rego.mdc
+- .cursor/rules/n-security.mdc
+- .cursor/rules/n-style.mdc
+- .cursor/rules/n-test.mdc
+- .cursor/rules/n-text.mdc
+- .cursor/rules/n-tool-surface.mdc
+- .cursor/rules/n-vue.mdc
+- .cursor/rules/n-worktree.mdc
+- .cursor/rules/scripts.mdc
+
+## Skills
+
+- `.cursor/skills/mdc-check/SKILL.md` — Проаналізувати правило в npm/mdc: максимум перевірюваної логіки й деталей — у check-{id}.mjs з зрозумілими коментарями/JSDoc; у .mdc залишати людинозрозумілий зміст без дублювання алгоритму перевірки
+- `.cursor/skills/n-adr-normalize/SKILL.md` — Ручний запуск ADR-нормалізації — обхід порогу й min-interval, прогон одного батчу чернеток через LLM, перегляд результату через git diff
+- `.cursor/skills/n-doc-files/SKILL.md` — Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+- `.cursor/skills/n-lint/SKILL.md` — Запустити дельта-лінт (npx @7n/rules lint) по змінених файлах vs origin, виправити порушення й підтвердити чистий вихід
+- `.cursor/skills/n-llm-patch/SKILL.md` — Підготовка самодостатнього текстового промпта для іншого Claude/Cursor-агента — read-only аналіз CWD без жодних змін у поточному репо
+- `.cursor/skills/n-publish-telegram/SKILL.md` — Підготовка матеріалу з поточного контексту для публікації в Telegram-каналі команди
+- `.cursor/skills/n-taze/SKILL.md` — Оновлення версій модулів проекту з аналізом major-змін і автоматичним рефакторингом несумісного коду
+
+## Commands
+
+Generated from the root `package.json` on each `npx @7n/rules` sync. Prefer `bun run <script>` for project scripts.
+
+- **Залежності**: `bun i`
+- **test**: `bun run test`
+- **start**: `bun run start`
+- **Оновити правила та AGENTS.md** (після змін у правилах/шаблоні CLI): `npx @7n/rules`
+- **Перевірки правил (programmatic)**: `npx @7n/rules fix`
+- **knip (невикористані залежності та експорти)**: `bunx knip`
+
+## Instructions for all agents
+
+Before making changes, read the relevant rule files for the area you are working on.
+
+## Інваріант після змін
+
+`n-changelog.mdc` (alwaysApply) релевантне після **будь-якої** зміни файлів, не лише для релізу. Перед фінальною відповіддю виконай `npx @7n/rules fix changelog` (exit `0`) і познач результат рядком `Changelog: …` у відповіді.
+
+## Priority
+
+If rules conflict:
+
+1. AGENTS.md
+2. task-specific rule file
+3. core rule file
+
+## Language
+
+Respond in Ukrainian.
+Keep technical terms in English.
+
+## Behavior
+
+Do not ignore referenced rule files.
+Explicitly follow repository conventions before proposing or applying changes.
+
+</project_instructions>
+</project_context>
+
+## Поведінка
+
+Поведінка:
+
+1. Перевіряє наявність каталогу `npm/skills` у корені репозиторію. Якщо відсутній, операція завершується успіхом.
+2. Ітерується по всім підкаталогах у `npm/skills`. Для кожного каталогу виконується перевірка відповідності метаданих скіла.
+3. Для кожного скіла перевіряється, чи відсутній файл `auto.md`. Якщо знайдено, фіксується порушення, оскільки метадані мають знаходитися у `main.json`.
+4. Зчитується вміст `main.json` скіла. Якщо файл відсутній або недійсний, фіксується порушення.
+5. Виконується перевірка полів у `main.json` скіла:
+   - Перевіряється тип поля `worktree` — має бути булевим значенням.
+   - Якщо поле `auto` визначене, аналізується його значення на відповідність очікуваним форматам.
+   - Перевіряється тип поля `requireRoot` — має бути булевим значенням.
+   - Перевіряється узгодженість: якщо `worktree` дорівнює `true`, поле `requireRoot` не може бути `false`.
+   - Якщо поле `tier` визначене, воно має відповідати одному з визначених рівнів.
+6. Якщо всі перевірки для скіла успішно пройдені, фіксується успішний статус для цього скіла.
+7. Завершення виконання `main` та повернення коду виходу, що відображає кількість виявлених порушень.
+
+## Публічний API
+
+main — перевіряє, що всі файли `npm/skills/<id>/meta.json` відповідають встановленим вимогам.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/npm-module/skill_meta/main.mjs

@@ -0,0 +1,91 @@
+/** @see ./docs/skill_meta.md */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createViolationReporter } from '@7n/rules/scripts/lib/lint-surface/violation-reporter.mjs'
+import { SKILL_TIERS, parseSkillAutoSpec, readSkillMetaRaw } from '@7n/rules/scripts/lib/skill-meta.mjs'
+
+/**
+ * Перевіряє поля сирого meta.json одного скіла (без auto.md / відсутності файлу).
+ * @param {string} id ідентифікатор скіла
+ * @param {Record<string, unknown>} raw сирий meta.json
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {boolean} true, якщо всі поля валідні
+ */
+function checkSkillFields(id, raw, reporter) {
+  let ok = true
+  if (typeof raw.worktree !== 'boolean') {
+    reporter.fail(`skills/${id}: main.json.worktree має бути boolean`)
+    ok = false
+  }
+  if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
+    reporter.fail(`skills/${id}: main.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+    ok = false
+  }
+  if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
+    reporter.fail(`skills/${id}: main.json.requireRoot має бути boolean`)
+    ok = false
+  }
+  if (raw.worktree === true && raw.requireRoot === false) {
+    reporter.fail(
+      `skills/${id}: requireRoot:false суперечить worktree:true (worktree вже вимагає кореня — прибери поле)`
+    )
+    ok = false
+  }
+  if (raw.tier !== undefined && !(typeof raw.tier === 'string' && SKILL_TIERS.includes(raw.tier))) {
+    const tierList = SKILL_TIERS.map(t => `"${t}"`).join(' | ')
+    reporter.fail(`skills/${id}: main.json.tier має бути ${tierList}`)
+    ok = false
+  }
+  return ok
+}
+
+/**
+ * Валідує meta.json одного скіла.
+ * @param {string} id ідентифікатор скіла
+ * @param {string} skillDir каталог скіла
+ * @param {ReturnType<typeof createViolationReporter>} reporter репортер
+ * @returns {void}
+ */
+function checkSkill(id, skillDir, reporter) {
+  let skillOk = true
+
+  if (existsSync(join(skillDir, 'auto.md'))) {
+    reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у main.json)`)
+    skillOk = false
+  }
+
+  const raw = readSkillMetaRaw(skillDir)
+  if (!raw) {
+    reporter.fail(`skills/${id}: відсутній або невалідний main.json (очікується {"auto"?, "worktree": bool})`)
+    return
+  }
+
+  if (!checkSkillFields(id, raw, reporter)) skillOk = false
+
+  if (skillOk) {
+    reporter.pass(`skills/${id}: main.json валідний`)
+  }
+}
+
+/**
+ * Валідує всі `npm/skills/<id>/meta.json`.
+ * @param {import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintContext} ctx контекст лінту.
+ * @returns {Promise<import('@7n/rules/scripts/lib/lint-surface/types.mjs').LintResult>} результат перевірки з порушеннями.
+ */
+export function lint(ctx) {
+  const cwd = ctx.cwd
+  const reporter = createViolationReporter(ctx)
+  const skillsDir = join(cwd, 'npm', 'skills')
+  if (!existsSync(skillsDir)) {
+    reporter.pass('npm/skills/ відсутній — немає скілів для валідації')
+    return Promise.resolve(reporter.result())
+  }
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    checkSkill(entry.name, join(skillsDir, entry.name), reporter)
+  }
+
+  return Promise.resolve(reporter.result())
+}

package/rules/npm-module/skill_meta/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` відхиляє.