@nitra/cursor 12.8.5 → 12.8.7

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [12.8.7] - 2026-06-22
+
+### Changed
+
+- ✨ feat(rules/abie): http_route_base.mdc + активація + ua-домени у ua_http_route.mdc
+
+## [12.8.6] - 2026-06-22
+
+### Changed
+
+- ✨ feat(rules/abie): http_route_base.mdc + активація + ua-домени у ua_http_route.mdc
+
 ## [12.8.5] - 2026-06-22
 
 ### Changed

package/bin/n-cursor.js

@@ -630,16 +630,16 @@ function buildClaudeLintParallelismSectionLines() {
 }
 
 /**
- * Рендерить секцію для CLAUDE.md: скіли з `meta.json.worktree === true` запускаються
+ * Рендерить секцію для CLAUDE.md: скіли з `main.json.worktree === true` запускаються
  * лише в окремому git-worktree (дублює fail-fast банер `SKILL.md` як завжди-читане правило).
  * @returns {string[]} рядки для вставки (з порожнім рядком на початку)
  */
 function buildClaudeWorktreeEnforcementSectionLines() {
   return [
     '',
-    '## Worktree-only skills (`meta.json` → `worktree: true`)',
+    '## Worktree-only skills (`main.json` → `worktree: true`)',
     '',
-    'Скіл із **`worktree: true`** у `meta.json` запускається **виключно** в окремому git-worktree (`.worktrees/<current-branch>-<suffix>/`) — **не** в основному дереві й **не** паралельно. Перший крок такого скіла (блок `n-cursor:worktree:start` у його `SKILL.md`) — **preflight**: якщо `git rev-parse --show-toplevel` не вказує під `.worktrees/`, **STOP** і не питай користувача про назву гілки; створи worktree від поточної гілки готовим snippet з `SKILL.md` за конвенцією `<current-branch>-<suffix>` і без shell expansion (без command substitution, variable expansion чи backticks). Чисте робоче дерево — **не** привід пропустити preflight.',
+    'Скіл із **`worktree: true`** у `main.json` запускається **виключно** в окремому git-worktree (`.worktrees/<current-branch>-<suffix>/`) — **не** в основному дереві й **не** паралельно. Перший крок такого скіла (блок `n-cursor:worktree:start` у його `SKILL.md`) — **preflight**: якщо `git rev-parse --show-toplevel` не вказує під `.worktrees/`, **STOP** і не питай користувача про назву гілки; створи worktree від поточної гілки готовим snippet з `SKILL.md` за конвенцією `<current-branch>-<suffix>` і без shell expansion (без command substitution, variable expansion чи backticks). Чисте робоче дерево — **не** привід пропустити preflight.',
     ''
   ]
 }
@@ -795,10 +795,10 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
         const rootOnly = !worktree && meta?.requireRoot === true
         const entries = await readdir(srcDir, { withFileTypes: true })
         for (const entry of entries) {
-          // Лише top-level файли скіла. `meta.json` — метадані (не для споживача);
+          // Лише top-level файли скіла. `main.json` — метадані (не для споживача);
           // підкаталоги (`js/` — скіл-специфічний код) виконуються з пакета через
           // `npx`, у проєкт не копіюються (як `npm/rules/<id>/js/`). Див. scripts.mdc.
-          if (!entry.isFile() || entry.name === 'meta.json') continue
+          if (!entry.isFile() || entry.name === 'main.json') continue
           let content = await readFile(join(srcDir, entry.name), 'utf8')
           if (entry.name === 'SKILL.md') {
             content = injectWorktreeNotice(content, worktree)

package/package.json

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

package/rules/abie/js/http_route_base.mdc

@@ -0,0 +1,25 @@
+## k8s: **HTTPRoute** у base-шарі — домени `aiml.live`
+
+У **HTTPRoute** під шляхом **`…/k8s/.../base/...`** (сегмент `base` у path) усі значення **`spec.hostnames`** мають належати до домену **`aiml.live`**: точна відповідність **`aiml.live`**, wildcard **`*.aiml.live`** або будь-який піддомен (**`api.aiml.live`**, **`app.aiml.live`** тощо). Перевірка — case-insensitive.
+
+Rego-пакет: **`abie.http_route_base`** (`policy/http_route_base/`). Цільові файли: `…/k8s/.../base/.../*.yaml` типу HTTPRoute.
+
+```yaml title="…/k8s/base/hr.yaml"
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: my-app
+spec:
+  hostnames:
+    - "my-app.aiml.live"   # ✓ піддомен aiml.live
+  parentRefs:
+    - name: gateway
+```
+
+Недозволені в base-шарі (але коректні для ua-overlay — `abie.app`, `vybeerai.com.ua`):
+
+```yaml
+  hostnames:
+    - "abie.app"            # ✗ ua-домен, не base
+    - "vybeerai.com.ua"     # ✗ ua-домен, не base
+```

package/rules/abie/js/ua_http_route.mdc

@@ -1,6 +1,6 @@
 ## k8s: overlay **HTTPRoute** (**ua**)
 
-За наявності **Deployment** під **k8s** і наявності **Vite** (**`vite.config.js`**, **`vite.config.mjs`** або **`vite.config.ts`** у каталозі пакета) у **`ua/kustomization.yaml`** цього пакета потрібні **inline JSON6902** у **`patches`**: **target** **`kind: HTTPRoute`**, **непорожній `name`** (як у маніфесті маршруту). Мають бути зміни **`/spec/hostnames`** (домени abie — у скрипті) та **`/spec/parentRefs/0/namespace`** (**`ua`**, також дозволені префікси **`ua-*`**, наприклад **`ua-b2b`**). Як обирати **`op`** (**add** / **replace** тощо) у patch — **k8s.mdc** (розділ про JSON patch у kustomization).
+За наявності **Deployment** під **k8s** і наявності **Vite** (**`vite.config.js`**, **`vite.config.mjs`** або **`vite.config.ts`** у каталозі пакета) у **`ua/kustomization.yaml`** цього пакета потрібні **inline JSON6902** у **`patches`**: **target** **`kind: HTTPRoute`**, **непорожній `name`** (як у маніфесті маршруту). Мають бути зміни **`/spec/hostnames`** (хоча б один з доменів: **`abie.app`**, **`vybeerai.com.ua`**, **`*.abie.app`**, **`*.vybeerai.com.ua`**) та **`/spec/parentRefs/0/namespace`** (**`ua`**, також дозволені префікси **`ua-*`**, наприклад **`ua-b2b`**). Як обирати **`op`** (**add** / **replace** тощо) у patch — **k8s.mdc** (розділ про JSON patch у kustomization).
 
 ### HTTPRoute: спільні сервіси **`auth-run-hl`**, **`file-link-hl`**
 

package/rules/abie/main.mdc

@@ -6,8 +6,20 @@ version: '1.22'
 
 Правило **abie** для споживачів **@nitra/cursor**: **k8s** (Deployment + **HealthCheckPolicy** у **`hc.yaml`**, overlay **ua** — **nodeSelector**, **HTTPRoute** (будь-який непорожній **`target.name`**, для спільних сервісів **`auth-run-hl`** / **`file-link-hl`** — **`namespace: dev`** у base та patch **`…/backendRefs/…/namespace`** у **ua**)), гілки **dev**, **ua** у **clean-merged-branch**, а також заборона тримати артефакти **Firebase Hosting** у **підкаталогах першого рівня** (безпосередні діти кореня репозиторію; у самому корені ці імена не вимагаються до видалення).
 
+## Активація
+
+Правило активується через **`.n-cursor.json`** у корені репозиторію:
+
+```json
+{ "rules": ["abie"] }
+```
+
+Без цього запису `@nitra/cursor` пропускає всі abie-перевірки (JS-концерни та rego-полісі).
+
 [k8s-hc-yaml](./js/hc_pairing.mdc)
 
+[k8s-http-route-base](./js/http_route_base.mdc)
+
 [k8s-http-route-ua](./js/ua_http_route.mdc)
 
 [k8s-nodeselector](./js/ua_node_selector.mdc)

package/rules/adr/js/hooks.mdc

@@ -0,0 +1,32 @@
+## JS-перевірки хуків і конфігурації (`hooks.mjs`)
+
+`js/hooks.mjs` перевіряє відповідність проєкту правилу `adr` через шість незалежних перевірок:
+
+### 1. Канонічність скриптів хуків
+
+Для кожного з двох bash-скриптів (`capture-decisions.sh`, `normalize-decisions.sh`) перевіряє:
+
+- файл `.claude/hooks/<script>.sh` **існує** у проєкті;
+- його вміст **ідентичний** bundled-версії з пакета `@nitra/cursor`.
+
+Якщо файл відсутній або відрізняється — `fail` з підказкою `npx @nitra/cursor`.
+
+### 2. Наявність `.claude/settings.json`
+
+Перевіряє **існування** project-shared файлу `.claude/settings.json`. Структуру хуків всередині (наявність `hooks.Stop[]` з відповідними маркерами) валідує окрема Rego-полісі `adr.settings_json`.
+
+### 3. Cursor hooks config
+
+Читає `.cursor/hooks.json` і перевіряє, чи кожен зі скриптів (`capture-decisions.sh`, `normalize-decisions.sh`) присутній у `hooks.stop[*].command` як підрядок-маркер.
+
+### 4. `.gitignore` для лог-файлів хуків
+
+Перевіряє, чи покриває `.gitignore` лог-файли `.claude/hooks/capture-decisions.log` і `.claude/hooks/normalize-decisions.log`. Допустимі форми покриття:
+
+- точний шлях (`.claude/hooks/capture-decisions.log`)
+- glob `.claude/hooks/*.log` або `.claude/hooks/**/*.log`
+- широкий glob `*.log` або `**/*.log`
+
+### 5. Доступність LLM CLI
+
+Інформативна (завжди `pass`) перевірка наявності хоча б одного з `claude` або `cursor-agent` у `PATH`. Якщо жодного немає — хук просто мовчки no-op'ає, тому це попередження, а не помилка.

package/rules/adr/js/madr_format.mdc

@@ -0,0 +1,96 @@
+## MADR v4 і дві фази
+
+ADR живуть у єдиному каталозі **`docs/adr/`**. Clean ADR-и мають формат **MADR v4.0.0 minimal** з **OKF v0.1 frontmatter** і точними section headings англійською:
+
+- `## Context and Problem Statement`
+- `## Considered Options`
+- `## Decision Outcome`
+- `### Consequences`
+- `## More Information`
+
+Вміст секцій — українською, code identifiers / paths / commands — як у transcript. Якщо transcript не містить альтернатив або підтверджених наслідків, hook має явно писати `Інші варіанти в transcript не обговорювалися.` або `transcript не містить підтвердження ...`, а не вигадувати відсутні факти.
+
+Є два стани файлу, які відрізняються YAML frontmatter:
+
+- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYMMDD-HHMM-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
+- **Clean** — файл з OKF v0.1 frontmatter (`type: ADR`, `title:`, `description:`) і kebab-case-іменем. Заголовок `#` у тілі не потрібен — `title:` у frontmatter вже є заголовком. `normalize-decisions.sh` зберігає timestamp-префікс чернетки → `YYMMDD-HHMM-<slug>.md` (наприклад `260518-0928-ланцюжок-запуску-abie.md`); створений руками clean-файл може мати просто `<slug>.md`.
+
+`normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
+
+### Фаза 1 — Capture
+
+Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з evidence-bound промптом і записує результат у **`docs/adr/<timestamp>-<session>.md`**, якщо модель повернула MADR-блок з шапкою `## ADR …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
+
+Для Cursor payload скрипт бере `transcript_path`, `conversation_id` / `generation_id` і `workspace_roots[0]`; для Claude Code — `transcript_path`, `session_id` і `CLAUDE_PROJECT_DIR`.
+
+**Tooling-only skip:** перед викликом LLM `capture-decisions.sh` дивиться у transcript на `tool_use`-правки (`Edit`/`Write`/`MultiEdit`). Якщо всі змінені файли потрапляють у вузький allowlist — `.cspell.json`, `docs/adr/*.md`, `CHANGELOG.md`, кореневі `AGENTS.md`/`CLAUDE.md`, або `package.json` з diff виключно по ключу `version` — хук виходить з `exit 0` без LLM-виклику. Це розриває петлю «`/n-lint` править `.cspell.json` → з'являється новий ADR-draft → наступний `/n-lint` знов псує правопис у цьому draft». Поведінку вимикає `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0`.
+
+### Фаза 2 — Normalize
+
+Stop-hook `normalize-decisions.sh` спрацьовує на тому самому `Stop`-евенті, але:
+
+- Виходить миттєво, якщо чернеток (`session:` у frontmatter) менше ніж **`ADR_NORMALIZE_THRESHOLD`** (default 30).
+- Виходить миттєво, якщо від попередньої спроби пройшло менше **`ADR_NORMALIZE_MIN_INTERVAL_HOURS`** годин (default 6) — щоб не крутитися щоразу, коли поріг постійний.
+- Бере не більше **`ADR_NORMALIZE_BATCH`** чернеток (default 10, найстарші за іменем-timestamp), формує один промпт LLM і чекає JSON-відповідь зі списком операцій.
+- Виходить миттєво, якщо репозиторій у стані `MERGE_HEAD` / `rebase-*` — небезпечно правити файли посеред конфлікту.
+- Виходить миттєво, якщо інший normalize-запуск тримає `flock` на `.claude/hooks/.normalize.lock` (тільки де `flock` доступний).
+- Перед викликом LLM для кожної чернетки batch'а читає `transcript:` із frontmatter і той самий tool_use-список. Чернетки tooling-only — видаляє без виклику LLM. Якщо після фільтра batch порожній — `exit 0`.
+
+LLM повертає масив операцій:
+
+| `op` | Семантика | Поля |
+| --- | --- | --- |
+| `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
+| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: frontmatter знімається, ім'я → `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено), додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. | `file`, `slug`, `content` |
+| `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. | `file`, `target`, `additions` |
+
+`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. До імені clean-файлу скрипт додає `YYMMDD-HHMM-` чернетки, тож запис лишається прив'язаним до часу capture, а `docs/adr/` сортується хронологічно. Колізія імен обробляється детермінованим суфіксом `-2`, `-3`. Старі чернетки з `YYYYMMDD-HHMMSS-` prefix нормалізатор також розпізнає, щоб не ламати наявний inbox.
+
+### Жодних git-операцій
+
+`normalize-decisions.sh` **не комітить, не `git add`, нічого з git**. Усі зміни — у робочому дереві. Розробник у зручний момент дивиться `git status` / `git diff` і вирішує: `git add` + commit, `git checkout -- <file>` для відкату, або правки руками. Це і є review-вікно.
+
+### Recursion guard і ENV-керування
+
+Інший LLM CLI, який запустить normalize, успадковує `ADR_NORMALIZE_RUNNING=1` — внутрішній Stop-hook вийде відразу. Доступні ENV:
+
+| Змінна | Default | Призначення |
+| --- | --- | --- |
+| `ADR_NORMALIZE_THRESHOLD` | `30` | Поріг чернеток для запуску фази. |
+| `ADR_NORMALIZE_BATCH` | `10` | Максимум чернеток у одному виклику LLM. |
+| `ADR_NORMALIZE_MIN_INTERVAL_HOURS` | `6` | Мінімум між спробами (навіть якщо поріг). |
+| `ADR_NORMALIZE_DRY` | `0` | `1` — лише лог запланованих операцій, без змін на диску. |
+| `ADR_NORMALIZE_MODEL` | `sonnet` | Модель для `claude -p`. |
+| `ADR_NORMALIZE_CURSOR_MODEL` | `claude-4.6-sonnet-medium` | Модель для `cursor-agent -p`. |
+| `ADR_NORMALIZE_SKIP_TOOLING_ONLY` | `1` | `0` — вимкнути structural skip tooling-only сесій (старий behavior). |
+
+Для ручного запуску (поза порогом і поза Stop-хуком) є **`/n-adr-normalize`** — slash-команда тимчасово виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0` та викликає скрипт напряму.
+
+## LLM CLI: claude → cursor-agent fallback
+
+Обидва скрипти обирають доступний CLI (порядок фіксований):
+
+1. **`claude`** (Anthropic Claude Code CLI) — `claude -p --model "<model>"`.
+2. **`cursor-agent`** (Cursor IDE CLI) — `cursor-agent -p --mode ask --output-format text --model "<model>"`.
+3. Жодного CLI у `PATH` — скрипт виходить з кодом `0` і нічого не пише.
+
+`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації / нормалізації інструменти не потрібні.
+
+## Структура каталогу
+
+```text
+docs/adr/
+├── YYMMDD-HHMM-<sid>.md       # drafts (frontmatter session:/captured:/transcript:)
+└── YYMMDD-HHMM-<slug>.md      # clean ADR-и (без frontmatter, timestamp-префікс чернетки збережено)
+.claude/hooks/
+├── capture-decisions.sh       # auto-synced з пакета
+├── normalize-decisions.sh     # auto-synced з пакета
+├── capture-decisions.log      # лог запусків capture (НЕ коміти)
+├── normalize-decisions.log    # лог запусків normalize (НЕ коміти)
+├── .normalize-state           # timestamp останнього normalize-запуску (НЕ коміти)
+└── .normalize.lock            # lock-файл (НЕ коміти)
+.cursor/
+└── hooks.json                 # Cursor Agent stop-hooks для тих самих скриптів
+```
+
+`.gitignore` у корені проєкту повинен містити базові рядки (`node_modules/`, `dist/`, `*.secret`) і патерни для ADR Stop-hook (**`.claude/hooks/*.log`**, `.claude/hooks/.normalize-state`, `.claude/hooks/.normalize.lock`). Канонічний фрагмент (дописується `npx @nitra/cursor`, коли правило `adr` увімкнене): [.gitignore.snippet](./templates/hooks/.gitignore.snippet).

package/rules/adr/js/settings_policy.mdc

@@ -0,0 +1,34 @@
+## Rego-перевірки конфігурації settings.json
+
+### `adr.settings_json` — Stop-хуки у `.claude/settings.json`
+
+Пакет перевіряє, що project-shared `.claude/settings.json` містить **обидві** managed Stop-hook групи (ідентифікуються підрядком у `command`):
+
+| Маркер | Призначення |
+| --- | --- |
+| `.claude/hooks/capture-decisions.sh` | Capture-хук — запис чернеток ADR після сесії |
+| `.claude/hooks/normalize-decisions.sh` | Normalize-хук — батч-нормалізація чернеток |
+
+Помилка, якщо `hooks.Stop[*].hooks[*].command` не містить маркера для будь-якого зі скриптів.
+
+Запуск локально:
+
+```bash
+conftest test .claude/settings.json -p npm/rules/adr/policy \
+  --namespace adr.settings_json
+```
+
+### `adr.settings_local_json` — відсутність дублів у `.claude/settings.local.json`
+
+Пакет перевіряє **зворотне**: якщо `.claude/settings.local.json` існує, він **не повинен** містити жодного зі Stop-хуків `capture-decisions.sh` або `normalize-decisions.sh` — інакше кожен скрипт виконується **двічі** на одну Stop-подію.
+
+Помилка, якщо `hooks.Stop[*].hooks[*].command` знаходить маркер у local-файлі.
+
+Запуск локально:
+
+```bash
+conftest test .claude/settings.local.json -p npm/rules/adr/policy \
+  --namespace adr.settings_local_json
+```
+
+> Якщо хук колись був у `.claude/settings.local.json` — прибери дубль вручну після того, як переніс його до project-shared `settings.json`.

package/rules/adr/main.mdc

@@ -4,102 +4,9 @@ alwaysApply: true
 version: '2.2'
 ---
 
-## MADR v4 і дві фази
+Правило `adr` автоматично фіксує архітектурні рішення (ADR) після кожної сесії через Stop-хуки і батч-нормалізує чернетки у канонічний формат MADR v4.
 
-ADR живуть у єдиному каталозі **`docs/adr/`**. Clean ADR-и мають формат **MADR v4.0.0 minimal** з **OKF v0.1 frontmatter** і точними section headings англійською:
-
-- `## Context and Problem Statement`
-- `## Considered Options`
-- `## Decision Outcome`
-- `### Consequences`
-- `## More Information`
-
-Вміст секцій — українською, code identifiers / paths / commands — як у transcript. Якщо transcript не містить альтернатив або підтверджених наслідків, hook має явно писати `Інші варіанти в transcript не обговорювалися.` або `transcript не містить підтвердження ...`, а не вигадувати відсутні факти.
-
-Є два стани файлу, які відрізняються YAML frontmatter:
-
-- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYMMDD-HHMM-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
-- **Clean** — файл з OKF v0.1 frontmatter (`type: ADR`, `title:`, `description:`) і kebab-case-іменем. Заголовок `#` у тілі не потрібен — `title:` у frontmatter вже є заголовком. `normalize-decisions.sh` зберігає timestamp-префікс чернетки → `YYMMDD-HHMM-<slug>.md` (наприклад `260518-0928-ланцюжок-запуску-abie.md`); створений руками clean-файл може мати просто `<slug>.md`.
-
-`normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
-
-### Фаза 1 — Capture
-
-Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з evidence-bound промптом і записує результат у **`docs/adr/<timestamp>-<session>.md`**, якщо модель повернула MADR-блок з шапкою `## ADR …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
-
-Для Cursor payload скрипт бере `transcript_path`, `conversation_id` / `generation_id` і `workspace_roots[0]`; для Claude Code — `transcript_path`, `session_id` і `CLAUDE_PROJECT_DIR`.
-
-**Tooling-only skip:** перед викликом LLM `capture-decisions.sh` дивиться у transcript на `tool_use`-правки (`Edit`/`Write`/`MultiEdit`). Якщо всі змінені файли потрапляють у вузький allowlist — `.cspell.json`, `docs/adr/*.md`, `CHANGELOG.md`, кореневі `AGENTS.md`/`CLAUDE.md`, або `package.json` з diff виключно по ключу `version` — хук виходить з `exit 0` без LLM-виклику. Це розриває петлю «`/n-lint` править `.cspell.json` → з'являється новий ADR-draft → наступний `/n-lint` знов псує правопис у цьому draft». Поведінку вимикає `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0`.
-
-### Фаза 2 — Normalize
-
-Stop-hook `normalize-decisions.sh` спрацьовує на тому самому `Stop`-евенті, але:
-
-- Виходить миттєво, якщо чернеток (`session:` у frontmatter) менше ніж **`ADR_NORMALIZE_THRESHOLD`** (default 30).
-- Виходить миттєво, якщо від попередньої спроби пройшло менше **`ADR_NORMALIZE_MIN_INTERVAL_HOURS`** годин (default 6) — щоб не крутитися щоразу, коли поріг постійний.
-- Бере не більше **`ADR_NORMALIZE_BATCH`** чернеток (default 10, найстарші за іменем-timestamp), формує один промпт LLM і чекає JSON-відповідь зі списком операцій.
-- Виходить миттєво, якщо репозиторій у стані `MERGE_HEAD` / `rebase-*` — небезпечно правити файли посеред конфлікту.
-- Виходить миттєво, якщо інший normalize-запуск тримає `flock` на `.claude/hooks/.normalize.lock` (тільки де `flock` доступний).
-- Перед викликом LLM для кожної чернетки batch'а читає `transcript:` із frontmatter і той самий tool_use-список. Чернетки tooling-only — видаляє без виклику LLM. Якщо після фільтра batch порожній — `exit 0`.
-
-LLM повертає масив операцій:
-
-| `op` | Семантика | Поля |
-| --- | --- | --- |
-| `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
-| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: frontmatter знімається, ім'я → `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено), додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. | `file`, `slug`, `content` |
-| `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. | `file`, `target`, `additions` |
-
-`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. До імені clean-файлу скрипт додає `YYMMDD-HHMM-` чернетки, тож запис лишається прив'язаним до часу capture, а `docs/adr/` сортується хронологічно. Колізія імен обробляється детермінованим суфіксом `-2`, `-3`. Старі чернетки з `YYYYMMDD-HHMMSS-` prefix нормалізатор також розпізнає, щоб не ламати наявний inbox.
-
-### Жодних git-операцій
-
-`normalize-decisions.sh` **не комітить, не `git add`, нічого з git**. Усі зміни — у робочому дереві. Розробник у зручний момент дивиться `git status` / `git diff` і вирішує: `git add` + commit, `git checkout -- <file>` для відкату, або правки руками. Це і є review-вікно.
-
-### Recursion guard і ENV-керування
-
-Інший LLM CLI, який запустить normalize, успадковує `ADR_NORMALIZE_RUNNING=1` — внутрішній Stop-hook вийде відразу. Доступні ENV:
-
-| Змінна | Default | Призначення |
-| --- | --- | --- |
-| `ADR_NORMALIZE_THRESHOLD` | `30` | Поріг чернеток для запуску фази. |
-| `ADR_NORMALIZE_BATCH` | `10` | Максимум чернеток у одному виклику LLM. |
-| `ADR_NORMALIZE_MIN_INTERVAL_HOURS` | `6` | Мінімум між спробами (навіть якщо поріг). |
-| `ADR_NORMALIZE_DRY` | `0` | `1` — лише лог запланованих операцій, без змін на диску. |
-| `ADR_NORMALIZE_MODEL` | `sonnet` | Модель для `claude -p`. |
-| `ADR_NORMALIZE_CURSOR_MODEL` | `claude-4.6-sonnet-medium` | Модель для `cursor-agent -p`. |
-| `ADR_NORMALIZE_SKIP_TOOLING_ONLY` | `1` | `0` — вимкнути structural skip tooling-only сесій (старий behavior). |
-
-Для ручного запуску (поза порогом і поза Stop-хуком) є **`/n-adr-normalize`** — slash-команда тимчасово виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0` та викликає скрипт напряму.
-
-## LLM CLI: claude → cursor-agent fallback
-
-Обидва скрипти обирають доступний CLI (порядок фіксований):
-
-1. **`claude`** (Anthropic Claude Code CLI) — `claude -p --model "<model>"`.
-2. **`cursor-agent`** (Cursor IDE CLI) — `cursor-agent -p --mode ask --output-format text --model "<model>"`.
-3. Жодного CLI у `PATH` — скрипт виходить з кодом `0` і нічого не пише.
-
-`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації / нормалізації інструменти не потрібні.
-
-## Структура каталогу
-
-```text
-docs/adr/
-├── YYMMDD-HHMM-<sid>.md       # drafts (frontmatter session:/captured:/transcript:)
-└── YYMMDD-HHMM-<slug>.md      # clean ADR-и (без frontmatter, timestamp-префікс чернетки збережено)
-.claude/hooks/
-├── capture-decisions.sh       # auto-synced з пакета
-├── normalize-decisions.sh     # auto-synced з пакета
-├── capture-decisions.log      # лог запусків capture (НЕ коміти)
-├── normalize-decisions.log    # лог запусків normalize (НЕ коміти)
-├── .normalize-state           # timestamp останнього normalize-запуску (НЕ коміти)
-└── .normalize.lock            # lock-файл (НЕ коміти)
-.cursor/
-└── hooks.json                 # Cursor Agent stop-hooks для тих самих скриптів
-```
-
-`.gitignore` у корені проєкту повинен містити базові рядки (`node_modules/`, `dist/`, `*.secret`) і патерни для ADR Stop-hook (**`.claude/hooks/*.log`**, `.claude/hooks/.normalize-state`, `.claude/hooks/.normalize.lock`). Канонічний фрагмент (дописується `npx @nitra/cursor`, коли правило `adr` увімкнене): [.gitignore.snippet](./js/templates/hooks/.gitignore.snippet).
+[adr-madr-format](./js/madr_format.mdc)
 
 ## Stop-hook у `.claude/settings.json`
 
@@ -161,3 +68,14 @@ Cursor Agent читає project-level **`.cursor/hooks.json`**. `npx @nitra/curs
 ```
 
 Обидва Stop-hook'и ADR живуть у **project-shared** `.claude/settings.json` (закомічений), щоб механізм працював у всіх членів команди. Якщо хук колись був у `.claude/settings.local.json` — прибери дубль вручну: project-shared і local-копія створили б два запуски на одну подію.
+
+## Швидкий gate через conftest
+
+| Namespace | Файл | Що перевіряє |
+| --- | --- | --- |
+| `adr.settings_json` | `.claude/settings.json` | Наявність обох Stop-хуків у `hooks.Stop[]` |
+| `adr.settings_local_json` | `.claude/settings.local.json` | Відсутність дублів Stop-хуків у local-файлі |
+
+[adr-settings-policy](./js/settings_policy.mdc)
+
+[adr-hooks](./js/hooks.mdc)

package/rules/bun/js/bunfig.mdc

@@ -0,0 +1,12 @@
+## Конфігурація bunfig.toml
+
+У корені репозиторію має бути **`bunfig.toml`** з **hoisted** лінкером (пласке `node_modules`, сумісне з інструментами, які не розуміють ізольований layout Bun).
+
+Канон `bunfig.toml`: [bunfig.toml.snippet.toml](./policy/bunfig/template/bunfig.toml.snippet.toml)
+
+```toml
+[install]
+linker = "hoisted"
+```
+
+Rego-перевірка (`bun.bunfig`) порівнює кожен leaf-ключ у секції із канонічним значенням зі snippet-шаблону. Якщо секція `[install]` відсутня або не є обʼєктом — повідомляє про відсутність секції; якщо значення ключа не збігається — вказує очікуване.

package/rules/bun/js/layout.mdc

@@ -0,0 +1,60 @@
+## Структура lockfile та менеджер пакетів
+
+Проект використовує **тільки Bun** для керування залежностями та запуску скриптів.
+
+**Заборонені lockfile / директорії** (мають бути відсутні у репозиторії):
+
+- `package-lock.json`
+- `yarn.lock`
+- `pnpm-lock.yaml`
+- `.yarnrc.yml`
+- `.yarn/`
+
+Якщо якийсь із цих файлів чи директорій існує — **видали** його.
+
+**Обовʼязковий lockfile:** `bun.lock` (має бути присутній у корені).
+
+**Заборонені команди менеджерів пакетів:**
+
+- `npm install`, `yarn`, `pnpm` і їх відповідники lockfile (крім `bun.lock`)
+
+**Дозволені команди:**
+
+- `bun i`
+- `bun run <script>`
+- `bun add <pkg>`
+- `bun add -d <pkg>`
+- `bun remove <pkg>`
+- `bunx <tool>`
+- `npx <tool>` — якщо у проєкті вже використовується `npx` (не замінюй на `bunx`)
+
+**Одноразові CLI (`bunx` / `npx`):**
+
+- Якщо в проєкті вже використовується **`npx`** (скрипти, CI, Dockerfile) — **залишай `npx`**, не замінюй на `bunx`.
+- Якщо новий виклик CLI додається з нуля і в репозиторії прийнято лише Bun — можна `bunx <tool>`.
+
+**Не додавай** у `dependencies` / `devDependencies` пакети, які **використовуються лише як CLI** і їх достатньо викликати через **`bunx <pkg>`** (або **`npx`**, якщо в проєкті так прийнято): наприклад **oxlint**, **jscpd**, **eslint** у корені тощо. Виняток — пакет потрібен як **бібліотека** (імпорт у коді), peer для іншого пакета, або інструмент **не** покривається `bunx` у вашому CI.
+
+**Monorepo:**
+
+- Встановлювати залежності у відповідному пакеті, а не в корені без потреби.
+- Якщо залежність потрібна лише одному пакету, додавати її в директорії цього пакета.
+- У CI та локально запускати скрипти через `bun run`.
+
+**Dockerfile:**
+
+```dockerfile
+FROM oven/bun:alpine AS build-env
+```
+
+замість образу node.
+
+**GitHub Actions:** не вставляй у workflow окремі кроки **`actions/setup-node`**, **`oven-sh/setup-bun`**, **`actions/cache`** та **`bun install`** — їх **заборонено** дублювати в кожному job; завжди використовуй **локальний composite** (деталі й заборона дублювання — **ga.mdc**). Під капотом composite уже містить Node **24**, Bun, кеш і **`bun install --frozen-lockfile`**.
+
+Після **`actions/checkout@v6`** (`persist-credentials: false`):
+
+```yaml
+- uses: ./.github/actions/setup-bun-deps
+```
+
+Якщо в репозиторії action збережено під **`./npm/github-actions/setup-bun-deps`**, у `uses:` вкажи цей шлях замість `.github/actions/…` (**ga.mdc**).

package/rules/bun/js/lint.mdc

@@ -0,0 +1,9 @@
+## Лінт через n-cursor
+
+Лінт запускається через CLI **`n-cursor`**, **не** через `package.json`-скрипти:
+
+- **`n-cursor lint --full`** — весь репо: активні у `.n-cursor.json` правила (per-file + full лінтери за `meta.json#lint` scope, конформність) + `oxfmt` у кінці (fix-режим);
+- **`n-cursor lint`** — дельта vs origin (активні у `.n-cursor.json` per-file лінтери лише змінених файлів);
+- **`n-cursor lint <rule…>`** — конкретні правила (лінтер + конформність), напр. **`n-cursor lint ga`**.
+
+У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI `n-cursor`. У CI кожен workflow викликає **`n-cursor lint <rule> --read-only`** напряму (без обгорток).

package/rules/bun/js/package_json.mdc

@@ -0,0 +1,19 @@
+## Кореневий package.json
+
+В кореневому `package.json` не повинно бути `dependencies`, а в `devDependencies` — тільки модулі `@nitra/*`.
+
+**Дозволені винятки у `devDependencies` кореня (root-only):**
+
+- `vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner` — Vitest/Stryker peer/tools для `n-cursor coverage`
+- `@playwright/test` — для e2e-тестів
+
+Тримати їх **у корені** доводиться у будь-якому монорепо-споживачі, бо правило `test` enabled завжди (`test/auto.md` = `завжди`), а класти ці пакети у workspace-и не можна: published пакети (`npm-module.mdc`) не мають `devDependencies`, а інші workspace-и однаково запускають coverage оркестратор з кореня.
+
+**Заборонені top-level поля** у root `package.json` (з причинами): [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
+
+| Поле | Причина |
+|---|---|
+| `packageManager` | Видали поле — Bun не потребує `packageManager` |
+| `dependencies` | Кореневий `package.json` не повинен містити `dependencies` — додай у workspace-пакети |
+
+Якщо в `package.json` є поле `packageManager` — прибрати його, також прибрати всі директорії та файли для yarn.

package/rules/bun/main.mdc

@@ -7,69 +7,17 @@ version: '2.1'
 
 Проект використовує тільки Bun для керування залежностями та запуску скриптів.
 
-**Одноразові CLI (hasura, eslint, vite, cypress тощо):**
+[bun-layout](./js/layout.mdc)
 
-- Якщо в проєкті вже використовується **`npx`** (скрипти, CI, Dockerfile) — **залишай `npx`**, не замінюй на `bunx`.
-- Якщо новий виклик CLI додається з нуля і в цьому репозиторії прийнято лише Bun — можна `bunx <tool>`.
+[bun-bunfig](./js/bunfig.mdc)
 
-Заборонено використовувати як менеджер пакетів / lockfile:
+[bun-package_json](./js/package_json.mdc)
 
-- `npm install`, `yarn`, `pnpm` (і відповідні lockfile, крім `bun.lock`)
+[bun-lint](./js/lint.mdc)
 
-Дозволені команди:
+## Швидкий gate через conftest
 
-- `bun i`
-- `bun run <script>`
-- `bun add <pkg>`
-- `bun add -d <pkg>`
-- `bun remove <pkg>`
-- `bunx <tool>`
-- `npx <tool>`
-
-**Не додавай** у `dependencies` / `devDependencies` пакети, які **використовуються лише як CLI** і їх достатньо викликати через **`bunx <pkg>`** (або **`npx`**, якщо в проєкті так прийнято): наприклад **oxlint**, **jscpd**, **eslint** у корені тощо. Виняток — пакет потрібен як **бібліотека** (імпорт у коді), peer для іншого пакета, або інструмент **не** покривається `bunx` у вашому CI.
-
-Lockfile у репозиторії: `bun.lock`.
-Не створювати `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`.
-Видалити якщо вони є. Видалити .yarn та .yarnrc.yml якщо вони є.
-
-У корені репозиторію має бути **`bunfig.toml`** з **hoisted** лінкером (пласке `node_modules`, сумісне з інструментами, які не розуміють ізольований layout Bun):
-
-- Канон `bunfig.toml`: [bunfig.toml.snippet.toml](./policy/bunfig/template/bunfig.toml.snippet.toml)
-
-Для Bun monorepo:
-
-- Встановлювати залежності у відповідному пакеті, а не в корені без потреби.
-- Якщо залежність потрібна лише одному пакету, додавати її в директорії цього пакета.
-- У CI та локально запускати скрипти через `bun run`.
-
-В кореневому `package.json` не повинно бути `dependencies`, а в `devDependencies` — тільки модулі `@nitra/*`. **Виняток (root-only)** — Vitest/Stryker peer/tools для `n-cursor coverage`: `vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`; а також `@playwright/test` для e2e-тестів. Тримати їх **у корені** доводиться у будь-якому монорепо-споживачі, бо правило `test` enabled завжди (`test/auto.md` = `завжди`), а класти ці пакети у workspace-и не можна: published пакети (`npm-module.mdc`) не мають мати `devDependencies`, а інші workspace-и однаково запускають coverage оркестратор з кореня. Якщо в package.json є поля `packageManager`, то прибрати їх, також прибрати всі директорії та файли для yarn.
-
-- Заборонені top-level поля у root `package.json` (з причинами): [package.json.deny.json](./policy/package_json/template/package.json.deny.json)
-
-Коли зміна відбувається в Dockerfile, то використовувати
-
-```dockerfile
-FROM oven/bun:alpine AS build-env
-```
-
-замість образу node
-
-У **GitHub Actions** не вставляй у workflow окремі кроки **`actions/setup-node`**, **`oven-sh/setup-bun`**, **`actions/cache`** та **`bun install`** — їх **заборонено** дублювати в кожному job; завжди використовуй **локальний composite** (деталі й заборона дублювання — **ga.mdc**). Під капотом composite уже містить Node **24**, Bun, кеш і **`bun install --frozen-lockfile`**.
-
-Після **`actions/checkout@v6`** (`persist-credentials: false`):
-
-```yaml
-- uses: ./.github/actions/setup-bun-deps
-```
-
-Якщо в репозиторії action збережено під **`./npm/github-actions/setup-bun-deps`**, у `uses:` вкажи цей шлях замість `.github/actions/…` (**ga.mdc**).
-
-## lint
-
-Лінт запускається через CLI **`n-cursor`**, **не** через `package.json`-скрипти:
-
-- **`n-cursor lint --full`** — весь репо: активні у `.n-cursor.json` правила (per-file + full лінтери за `meta.json#lint` scope, конформність) + `oxfmt` у кінці (fix-режим);
-- **`n-cursor lint`** — дельта vs origin (активні у `.n-cursor.json` per-file лінтери лише змінених файлів);
-- **`n-cursor lint <rule…>`** — конкретні правила (лінтер + конформність), напр. **`n-cursor lint ga`**.
-
-У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI `n-cursor`. У CI кожен workflow викликає **`n-cursor lint <rule> --read-only`** напряму (без обгорток).
+| Namespace | Що перевіряє |
+|---|---|
+| `bun.bunfig` | Відповідність `bunfig.toml` канонічному шаблону (секції + leaf-ключі) |
+| `bun.package_json` | Заборонені top-level поля у root `package.json`; `devDependencies` лише `@nitra/*` + root-only test peers |