@7n/rules 1.0.0

package/rules/worktree/main.mdc

@@ -0,0 +1,100 @@
+---
+description: Конвенція git-worktree у цьому репо — створення, інвентаризація та прибирання через `npx @7n/mt worktree`.
+globs:
+alwaysApply: true
+---
+
+# Worktree-конвенція
+
+Усі git-worktree створюй і прибирай через `npx @7n/mt worktree` — він кладе їх у
+`.worktrees/` (gitignored, checkout `<sanit>/`) і веде інвентарний файл-опис у `.worktrees/.meta/`.
+
+## Розташування
+
+```
+.worktrees/
+  feat-skill-meta/        ← git worktree checkout
+  feat-skill-meta.md      ← інвентарний опис поруч (gitignored через .worktrees/)
+```
+
+Слеш у гілці перетворюється на дефіс: `feat/skill-meta` → `.worktrees/feat-skill-meta/`.
+Git-гілка лишається з оригінальним імʼям (`feat/skill-meta`).
+
+## Налаштування редакторів
+
+Worktree-каталоги — це вкладені копії всього дерева. Якщо редактор індексує їх,
+пошук дає дублі, а file-watcher вантажить диск. Тому редактор має **виключити**
+`.worktrees/` (а для Zed ще й приватний `.claude/worktrees/`) з пошуку та сканування.
+
+Канон перевіряється **лише** якщо файл налаштувань уже є — проєктам без VS Code / Zed
+нічого не нав'язується.
+
+### VS Code
+
+У `.vscode/settings.json` обовʼязково виключи `**/.worktrees/**` з пошуку і з дерева
+файлів. `node_modules` додавати не треба — VS Code виключає його з пошуку дефолтно.
+
+```json title=".vscode/settings.json"
+{
+  "search.exclude": {
+    "**/.worktrees/**": true
+  },
+  "files.exclude": {
+    "**/.worktrees/**": true
+  }
+}
+```
+
+Канон (subset — інші ключі дозволені): [settings.json.snippet.json](./vscode_settings/template/settings.json.snippet.json)
+
+### Zed
+
+Zed **замінює** масив `file_scan_exclusions` цілком (не зливає з дефолтами), тому в
+`.zed/settings.json` перелічуй і дефолти Zed, і `**/.worktrees`, і `**/.claude/worktrees`.
+Перевірка вимагає **всі** записи канону (бо інакше дефолти губляться).
+
+```json title=".zed/settings.json"
+{
+  "file_scan_exclusions": [
+    "**/.git",
+    "**/.svn",
+    "**/.hg",
+    "**/.DS_Store",
+    "**/Thumbs.db",
+    "**/node_modules",
+    "**/.worktrees",
+    "**/.claude/worktrees"
+  ]
+}
+```
+
+Канон (усі елементи обовʼязкові, зайві дозволені): [settings.json.snippet.json](./zed_settings/template/settings.json.snippet.json)
+
+`.zed/settings.json` без стабільної схеми в Schema Store — додай його до `.v8rignore` (як `.vscode/*`, див. **text.mdc**).
+
+## Команди
+
+- **Створити** (опис обовʼязковий): `npx @7n/mt worktree create <branch> "<навіщо>"`
+- **Інвентаризація**: `npx @7n/mt worktree list` (людино-) або `npx @7n/mt worktree inventory` (JSON)
+- **Прибрати** (ефемерний — прибирає й git-гілку): `npx @7n/mt worktree remove <branch>`
+- **Прибрати осиротілі інвентарі**: `npx @7n/mt worktree prune`
+
+## Завершення гілки worktree
+
+Коли робота у worktree завершена і її треба влити в базову гілку — **за замовчуванням пропонуй
+squash-merge** (уся гілка одним комітом), а не fast-forward чи merge-комітом. Worktree — це одна
+логічна задача, тож в історії базової гілки їй відповідає **один** коміт; проміжні TDD-коміти
+(«додав парсер», «видалив auto.md» тощо) у базовій гілці не потрібні. Реліз і `CHANGELOG`
+агрегуються за change-файлом, не за кількістю комітів, тож squash нічого не ламає.
+
+```bash
+git checkout <base> && git merge --squash <branch> && git commit
+```
+
+Якщо користувач явно просить зберегти поетапну історію — лише тоді fast-forward / merge-коміт.
+
+## Заборони
+
+- Не клади worktree в `.claude/worktrees/` — це приватна директорія харнесу Claude Code.
+- Не клади worktree в батьківський каталог `../cursor-<name>` — ускладнює інвентаризацію.
+- Не створюй worktree вручну (`git worktree add`) повз `npx @7n/mt worktree create` — інакше не буде інвентарного опису.

package/rules/worktree/vscode_settings/concern.json

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

package/rules/worktree/vscode_settings/template/settings.json.snippet.json

@@ -0,0 +1,8 @@
+{
+  "search.exclude": {
+    "**/.worktrees/**": true
+  },
+  "files.exclude": {
+    "**/.worktrees/**": true
+  }
+}

package/rules/worktree/zed_settings/concern.json

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

package/rules/worktree/zed_settings/template/settings.json.snippet.json

@@ -0,0 +1,12 @@
+{
+  "file_scan_exclusions": [
+    "**/.git",
+    "**/.svn",
+    "**/.hg",
+    "**/.DS_Store",
+    "**/Thumbs.db",
+    "**/node_modules",
+    "**/.worktrees",
+    "**/.claude/worktrees"
+  ]
+}

package/schemas/any.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Заглушка-схема: приймає будь-який валідний JSON. Для файлів без офіційної схеми (bespoke tool-конфіги, one-off артефакти), щоб v8r не падав через 'Could not find a schema'."
+}

package/schemas/concern.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "title": "Concern descriptor",
+  "description": "Маркер підкаталогу правила як concern-а. Кожна з поверхонь (check/policy/lint) опційна, але хоча б одна обов'язкова. Concern id = ім'я каталогу (lower snake_case [a-z0-9_]+).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri"
+    },
+    "fixability": {
+      "type": "string",
+      "enum": ["code", "config", "structural"],
+      "description": "Маршрутизація fix-движка. Усі мітки виконують детерміновану фазу T0; різниця — що після неї. `code` (дефолт, поле можна опускати) — джерельні порушення, які LLM може осмислено переписати → повна pi-agent-ladder (local→cloud) до чистого re-detect. `config` — canon/settings/tooling конфіг з єдиною правильною формою (jscpd/oxfmtrc/tooling/package_json/*_yml): фікс детермінований (T0/regen з канону), LLM лише вгадав би невалідне → після T0 fail-fast без ladder. `structural` — дублікати/розташування/структура (jscpd_duplicates/test-location/package-structure): авто-правка ризикована й потребує людського розсуду → після T0 fail-fast без ladder. config vs structural різняться мотивом пропуску (детермінований канон vs надто ризиковано) — для телеметрії й майбутнього routing."
+    },
+    "check": {
+      "type": "boolean",
+      "const": true,
+      "description": "JS conformance/fix поверхня. main.mjs має експортувати main(cwd)."
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Rego або template поверхня. Відповідає колишньому target.json. У unified lint surface (spec 2026-06-29) policy-concern генерує detector main.mjs через codegen; engine обирає Rego чи template. `files` опційне: порожній `policy: {}` — маркер policy-поверхні без явного файл-скоупу (скоуп резолвиться правилом).",
+      "properties": {
+        "engine": {
+          "type": "string",
+          "enum": ["rego", "template"],
+          "description": "rego → .rego через conftest; template → generic deep-subset. Канонічна заміна поля `check`."
+        },
+        "namespace": {
+          "type": "string",
+          "description": "Rego package/namespace concern-а (напр. `k8s.network_policy`) — для fix-hint маршрутизації по rego-повідомленнях."
+        },
+        "files": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["single"],
+              "properties": {
+                "single": { "type": "string", "minLength": 1 },
+                "required": { "type": "boolean" }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["walkGlob"],
+              "properties": {
+                "walkGlob": {
+                  "oneOf": [
+                    { "type": "string", "minLength": 1 },
+                    { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+                  ]
+                }
+              }
+            },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["glob"],
+              "properties": {
+                "glob": {
+                  "oneOf": [
+                    { "type": "string", "minLength": 1 },
+                    { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+                  ]
+                }
+              }
+            }
+          ]
+        },
+        "check": {
+          "type": "string",
+          "enum": ["template"],
+          "description": "template → generic deep-subset без .rego; без поля → Rego mode."
+        },
+        "missingMessage": {
+          "type": "string",
+          "description": "Override fail-повідомлення при відсутності required:single файла."
+        }
+      }
+    },
+    "lint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope"],
+      "description": "Lint поверхня. main.mjs має експортувати lint(changed, cwd, opts).",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["per-file", "full"],
+          "description": "per-file: delta-режим; full: крос-файловий."
+        },
+        "glob": {
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 } }
+          ],
+          "description": "per-file: фільтр delta-файлів; full: delta-тригер."
+        }
+      }
+    }
+  }
+}

package/schemas/layers-config.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/layers-config.json",
+  "title": "Конфіг шарової документації @7n/layers (<docsDir>/layers.json)",
+  "description": "Конфіг рушія шарової документації @7n/layers (репо nitra/mt, layers/schemas/layers.schema.json) — лежить у теці документації полігона (напр. npm/docs/layers.json).",
+  "type": "object",
+  "required": ["version", "docs"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "tier": { "enum": ["min", "avg", "max"] },
+    "maxTokens": { "type": "integer", "minimum": 256 },
+    "i18n": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "baseLang": { "type": "string", "minLength": 2 },
+        "langs": { "type": "array", "items": { "type": "string", "minLength": 2 } }
+      }
+    },
+    "docs": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["layer", "sources"],
+        "additionalProperties": false,
+        "properties": {
+          "layer": { "type": "string", "pattern": "^L\\d+$" },
+          "title": { "type": "string" },
+          "mode": { "enum": ["fragment"] },
+          "tier": { "enum": ["min", "avg", "max"] },
+          "sources": { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+        }
+      }
+    }
+  }
+}

package/schemas/n-rules.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/n-rules.json",
+  "title": "n-rules project config",
+  "description": "Конфігурація правил і skills для CLI @7n/rules (файл .n-rules.json у корені репозиторію).",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "Посилання на JSON Schema для автодоповнення та валідації в IDE; очікувано https://unpkg.com/@7n/rules/schemas/n-rules.json"
+    },
+    "rules": {
+      "type": "array",
+      "description": "Ідентифікатори правил без префікса n- (відповідають файлам n-<id>.mdc).",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "skills": {
+      "type": "array",
+      "description": "Ідентифікатори skills без префікса n- (у пакеті — підкаталог skills/<id>/, у проєкті після синку — .cursor/skills/n-<id>/). Якщо відсутній, CLI доповнить списком skills з пакету.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "disable-rules": {
+      "type": "array",
+      "description": "Список rule id (без префікса n-), які не потрібно автододавати в `.n-rules.json` під час запуску CLI.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "disable-skills": {
+      "type": "array",
+      "description": "Список skill id (без префікса n-), які не потрібно автододавати в `.n-rules.json` під час запуску CLI.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "ignore": {
+      "type": "array",
+      "description": "Директорії, що повністю виключаються з обходу check-скриптів CLI (npx @7n/rules fix ...) і AI-модифікацій (AI не редагує, не видаляє, не створює файли). Шляхи відносно кореня репозиторію (posix). Приклади: vendored Helm-чарти, генеровані маніфести, legacy-дерева. Стандартні виключення (node_modules, .git, dist, coverage, .turbo, .next) застосовуються завжди — додавати їх не треба.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "version": {
+      "type": "string",
+      "description": "Застаріле поле, ігнорується CLI. Правила завжди копіюються з каталогу mdc/ установленого пакету (node_modules або кеш npx); змініть версію через оновлення залежності."
+    },
+    "claude-config": {
+      "type": "boolean",
+      "description": "Чи синхронізувати `.claude/settings.json` (hooks + permissions, merge зі збереженням користувацьких полів) і slash-команди checks. За замовчуванням true.",
+      "default": true
+    }
+  },
+  "required": ["rules"]
+}

package/schemas/rule-meta.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/rule-meta.json",
+  "title": "n-rules rule meta",
+  "description": "Метадані правила @7n/rules: умова автоактивації (auto). Файл npm/rules/<id>/meta.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "auto": {
+      "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",
+      "oneOf": [
+        { "const": "завжди" },
+        { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 },
+        {
+          "type": "object",
+          "required": ["glob"],
+          "additionalProperties": false,
+          "properties": {
+            "glob": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["predicate"],
+          "additionalProperties": false,
+          "properties": {
+            "predicate": { "type": "string", "minLength": 1 },
+            "arg": {}
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/skill-meta.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/skill-meta.json",
+  "title": "n-rules skill meta",
+  "description": "Метадані скіла @7n/rules: умова автоактивації (auto) і чи виконувати в окремому git-worktree (worktree). Файл npm/skills/<id>/meta.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["worktree"],
+  "properties": {
+    "auto": {
+      "description": "Умова автоактивації: \"завжди\" або непорожній масив id правил, від яких залежить скіл.",
+      "oneOf": [
+        { "const": "завжди" },
+        { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+      ]
+    },
+    "worktree": {
+      "type": "boolean",
+      "description": "true — виконувати скіл в окремому git-worktree, один інстанс за раз (без паралельного запуску); false — у worktree не виконується."
+    },
+    "requireRoot": {
+      "type": "boolean",
+      "description": "true — скіл мутує CWD без worktree-ізоляції і має стартувати з кореня репо. Для worktree:true поле зайве (корінь гарантує worktree)."
+    },
+    "tier": {
+      "description": "Абстрактна тира моделі (capability, НЕ провайдер) для агентного виконання скіла через pi-runner: кожна каскадить local→cloud (напр. avg → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG), тож avg ≠ \"локальна\". За відсутності — \"max\" (відкриті скіли потребують сильної моделі).",
+      "enum": ["min", "avg", "max"]
+    }
+  }
+}

package/schemas/target.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@7n/rules/schemas/target.json",
+  "title": "Rego policy target manifest",
+  "description": "Маніфест поряд із <name>.rego: декларує, які файли проєкту фідити в conftest для цієї полісі. Лежить у npm/rules/<id>/policy/<name>/target.json (per-policy, поруч із <name>.rego). CLI читає й передає у runConftestBatch — JS-оркестратор у js/<name>/check.mjs не зобовʼязаний дублювати виклик. Namespace полісі обчислюється з шляху: <id>.<name>, відповідно `package <id>.<name>` у .rego.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["files"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "format": "uri",
+      "description": "Опційне посилання на JSON Schema для IDE-валідації; очікувано https://unpkg.com/@7n/rules/schemas/target.json"
+    },
+    "check": {
+      "type": "string",
+      "enum": ["template"],
+      "description": "Режим перевірки концерну. 'template' → без власного <name>.rego: канон зі template/<target>.snippet|deny|contains.<ext> звіряється generic deep-subset-ом (checkSnippet/checkDeny/checkContains/checkTextSubset). Сніпет — єдине джерело істини: його зміна одразу змінює enforce, без правок rego й міграторів. Без поля → класичний rego-режим (пара з <name>.rego)."
+    },
+    "files": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["single"],
+          "properties": {
+            "single": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Відносний шлях від кореня репозиторію (posix). Заборонені сегменти '..' і абсолютні шляхи."
+            },
+            "required": {
+              "type": "boolean",
+              "description": "true → fail при відсутності файла з відповідним missingMessage; false/відсутнє → silent skip (полісі не запускається). За замовчуванням false."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["walkGlob"],
+          "properties": {
+            "walkGlob": {
+              "oneOf": [
+                { "type": "string", "minLength": 1 },
+                {
+                  "type": "array",
+                  "minItems": 1,
+                  "items": { "type": "string", "minLength": 1 }
+                }
+              ],
+              "description": "Один або декілька picomatch-globів (matched проти відносного posix-шляху). walkDir від cwd із загальними skip-ами + .n-rules.json:ignore."
+            }
+          }
+        }
+      ]
+    },
+    "missingMessage": {
+      "type": "string",
+      "description": "Override дефолтного fail-повідомлення при відсутності required:single файла. Без значення CLI використає шаблон '<path> не існує (<id>.<name>)'."
+    }
+  }
+}