@nitra/cursor 12.8.6 → 12.8.8

package/rules/bun/main.mdc

@@ -7,69 +7,16 @@ 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>`
+[bun-policy-bunfig](./policy/bunfig/bunfig.mdc)
 
-**Не додавай** у `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`** напряму (без обгорток).
+[bun-policy-package_json](./policy/package_json/package_json.mdc)

package/rules/bun/policy/bunfig/bunfig.mdc

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

package/rules/bun/policy/package_json/package_json.mdc

@@ -0,0 +1,14 @@
+## Rego-gate: заборонені поля та devDependencies у кореневому package.json
+
+Rego-пакет: `bun.package_json`
+
+Цільовий файл: кореневий `package.json`.
+
+Список заборонених top-level полів (template-driven): [package.json.deny.json](./template/package.json.deny.json)
+
+Gate виносить два класи deny:
+
+1. **Заборонені top-level поля** — будь-яке поле з `package.json.deny.json` присутнє у файлі (навіть із порожнім значенням `{}`).
+2. **devDependencies не з білого списку** — дозволені лише `@nitra/*` та root-only тестові peer/tools (`vitest`, `@vitest/coverage-v8`, `@stryker-mutator/vitest-runner`, `@playwright/test`). Будь-який інший пакет → deny.
+
+Перевірки, що потребують FS або cross-file контексту (наприклад наявність `yarn.lock`), лишаються у JS-шарі.

package/rules/capacitor/js/ios_spm.mdc

@@ -0,0 +1,69 @@
+## iOS: лише SPM, виняток через Podfile
+
+### Правило за замовчуванням
+
+Не залишай `Podfile` (поза `Pods/`) у вихідному iOS-шарі, **якщо** уся потрібна
+iOS-функціональність (нативні плагіни/модулі) може працювати **лише** через **SPM** (Swift Package Manager).
+
+Перевірка рекурсивно шукає `Podfile` у `ios/`, пропускаючи `Pods/`, `build/`, `DerivedData/`.
+
+### Плагіни @nitra/
+
+Плагіни зі скоупу `@nitra/` за політикою **підтримують SPM** — перевіряти їх на SPM **не потрібно**
+(check не обходить `package.json` на предмет `@nitra/`).
+
+### Коли Podfile дозволений
+
+Якщо не вся потрібна iOS-функціональність поза `@nitra/` (сторонні Capacitor-плагіни, інша
+нативна залежність) доступна через SPM — `Podfile` дозволяється, але це **обов'язково** треба
+явно задати в кореневому **`package.json`** або в **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**:
+
+- **`"iosCocoaPodsBecausePluginsLackSpm": true`** — семантика: не вся потрібна нативна частина
+  поза `@nitra/` на SPM; `@nitra/` у це не входить;
+- або **`"iosCocoaPodsAllowed": true`** — короткий alias для того самого винятку.
+
+Без одного з цих прапорів `true` наявний `Podfile` поза `Pods/` вважається порушенням правила «лише SPM».
+
+**Де задати виняток у `package.json`:**
+
+```json
+{
+  "nitra": {
+    "iosCocoaPodsBecausePluginsLackSpm": true
+  }
+}
+```
+
+або коротший alias:
+
+```json
+{
+  "nitra": {
+    "iosCocoaPodsAllowed": true
+  }
+}
+```
+
+**Де задати виняток у `capacitor.config.json`:**
+
+```json
+{
+  "nitra": {
+    "iosCocoaPodsAllowed": true
+  }
+}
+```
+
+**Де задати виняток у `capacitor.config.ts` / `capacitor.config.mjs`:**
+
+```ts
+const config = {
+  // ...
+  nitra: {
+    iosCocoaPodsAllowed: true,
+  },
+}
+```
+
+Перевірка читає **лише** кореневі файли: `package.json`, потім capacitor-конфіги у корені.
+У `.ts` / `.mjs`: шукається блок `nitra { ... }` і на його тілі перевіряються ці boolean-поля.

package/rules/capacitor/js/version.mdc

@@ -0,0 +1,29 @@
+## Версія Capacitor
+
+У `package.json` (у **корені** репозиторію чи **workspace**-пакеті) оголошення **`@capacitor/core`**
+має вказувати діапазон, **сумісний лише з мажорною версією 8 і вище** (наприклад `^8.0.0`).
+**`*`**, `latest` і діапазони, де можлива 7-мажор, — неприйнятні.
+
+Перевірка обходить усі `package.json` у дереві (крім `node_modules`, `.git`, `dist`, `coverage`,
+`Pods`, `.turbo`, `.next`, `build`) і перевіряє нижню межу діапазону через `capacitorVersionRangeMinMajor`.
+Підтримуються `||`-частини, hyphen-range (`7 - 9`), `^`, `~`, `>=`, `>`, `=`, bare-version;
+`workspace:*` / `*` / `x` / `latest` — пропускаються (не блокують).
+
+**Приклади допустимих діапазонів:**
+
+```
+"@capacitor/core": "^8.0.0"
+"@capacitor/core": ">=8"
+"@capacitor/core": "8.x"
+"@capacitor/core": "workspace:*"
+```
+
+**Приклади неприйнятних діапазонів:**
+
+```
+"@capacitor/core": "^7.0.0"    // мажор 7 — занадто старий
+"@capacitor/core": "*"         // будь-яка — неприйнятна
+"@capacitor/core": "latest"    // неприйнятна
+"@capacitor/core": ">=6"       // нижня межа 6 — занадто старий
+"@capacitor/core": "6 - 9"     // hyphen-range: нижня межа 6 — неприйнятна
+```

package/rules/capacitor/main.mdc

@@ -5,30 +5,14 @@ alwaysApply: false
 version: '1.1'
 ---
 
-## Версія Capacitor
+Правило перевіряє версію `@capacitor/core` у `package.json` та коректність використання CocoaPods/SPM у iOS-шарі Capacitor-проєкту.
 
-У `package.json` (у **корені** репозиторію чи **workspace**-пакеті) оголошення **`@capacitor/core`**
-має вказувати діапазон, **сумісний лише з мажорною версією 8 і вище** (наприклад `^8.0.0`).
-**`*`**, `latest` і діапазони, де можлива 7-мажор, — неприйнятні.
+[capacitor-version](./js/version.mdc)
 
-## iOS: зазвичай лише SPM, виняток Podfile
+[capacitor-ios-spm](./js/ios_spm.mdc)
 
-- **Правило за замовчуванням:** не залишай `Podfile` (поза `Pods/`) у вихідному iOS-шарі, **якщо** уся потрібна
-  iOS-функціональність (нативні плагіни/модулі) може працювати **лише** через **SPM** (Swift Package Manager).
+## Швидкий gate через conftest
 
-- **Плагіни зі скоупу @nitra/:** за політикою вони **підтримуюють SPM**; **перевіряти** їх на **SPM** **не
-  потрібно** (і **check** цього **не** робить — **немає** обходу `package.json` на предмет **@nitra/**).
+[capacitor-package_json](./policy/package_json/package_json.mdc)
 
-- **Коли `Podfile` дозволений:** якщо **не** вся потрібна iOS-функціональність **поза** **@nitra/** (сторонні
-  **Capacitor**-плагіни, інша нативна залежність) **доступна** через **SPM** — `Podfile` **дозволяється**,
-  але це **обов’язково** треба явно задати в кореневому **`package.json`** або в
-  **`capacitor.config.json` / `capacitor.config.ts` / `capacitor.config.mjs`**
-
-  - **`"iosCocoaPodsBecausePluginsLackSpm": true`** (семантика: **не** **вся** потрібна нативна частина
-    **поза** **@nitra/** **на** **SPM**; **@nitra/** у це **не** входить);
-  - або **`"iosCocoaPodsAllowed": true`** (короткий **alias** для того самого **винятку**);
-
-  Без **одного** з цих прапорів `true` наявний **Podfile** поза **`Pods/`** вважається **порушенням** правила **«лише** **SPM**».
-
-- Перевірка читає **лише** кореневі файли: **`package.json`**, потім **capacitor-конфіги** у **корені** (див. вище).
-  У **`.ts` / `.mjs`**: шукається блок **nitra** `{ ... }` і **на його тілі** перевіряються ці **boolean**-поля.
+JS-перевірка (`platforms.mjs`) — authoritative: підтримує `||`-діапазони, hyphen-range, workspace-monorepo та iOS-специфічну логіку (Podfile).

package/rules/capacitor/policy/package_json/package_json.mdc

@@ -0,0 +1,9 @@
+## Rego-gate: версія `@capacitor/core` у `package.json`
+
+Rego-пакет: `capacitor.package_json`
+
+Цільовий файл: `package.json` (один файл, `target.json` → `files.single`).
+
+Перевіряє наявність `dependencies["@capacitor/core"]` і вимагає, щоб перша мажорна цифра діапазону була ≥ 8. Значення `workspace:*` пропускається без помилки.
+
+Спрощений порт JS-логіки: `||`-діапазони та hyphen-range — лише у JS (`fix.mjs`). Цей gate — швидка перевірка одиничного `package.json` (наприклад, через IDE або conftest у CI).

package/rules/changelog/js/agent-workflow.mdc

@@ -0,0 +1,15 @@
+## STOP — перед завершенням відповіді агента
+
+> **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
+
+1. **Поклади change-файл** `<ws>/.changes/YYMMDD-HHMM.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`. Якщо файл за ту саму хвилину вже існує, CLI атомарно створює `YYMMDD-HHMM-2.md`, потім `-3` тощо.
+2. **Ніколи** не редагуй `version` і `CHANGELOG.md` вручну — навіть для hotfix. Єдиний артефакт зміни — change-файл; `version`/CHANGELOG формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`). Будь-яка зміна `version` поза CI (drift від бази чи опублікованої) завалює `check changelog` — навіть якщо поряд є change-файл.
+3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (достатньо наявності change-файлу; `version` лишається незмінним).
+
+**Це правило релевантне завжди після будь-якої зміни** коду/конфігу/тестів/воркспейсу — **не** класифікуй його як «лише для релізу». Уже запущені тести чи білд **не** знімають вимогу changelog. Операційно перед фінальною відповіддю: `git status --short` → зіставити змінені шляхи з workspace-ами → change-файл для кожного релевантного workspace → `npx @nitra/cursor fix changelog` (exit `0`). Якщо у фінальній відповіді не можеш заповнити рядок `Changelog: …`, отже ти пропустив(ла) цей крок.
+
+**Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
+
+**Інверсія (change-файл не потрібен):** лише `docs/` / `doc/`; синхронізований із `@nitra/cursor` інструментарій (`.cursor/`, `.claude/`); лише `.gitignore`. **Корінь монорепо** (воркспейс `.` за наявності підпакетів) не перевіряється взагалі — отже й кореневі `AGENTS.md` / `CLAUDE.md` та bump `@nitra/cursor` у `devDependencies`. Окремого «релізного кроку» у feature-флоу немає — `version`/`CHANGELOG.md` змінює лише CI.
+
+**Pre-commit (людина):** `hk` у цьому репо запускає `fix changelog` при змінах під `npm/**` в **autofix-режимі** (env `N_CURSOR_CHANGELOG_AUTOFIX=1`): за відсутності change-файлу хук **сам** його створює (дефолти `patch`/`Changed`, опис = subject останнього коміту) і ставить у git-індекс, тож коміт не падає. Це лише підстраховка — агент не покладайся на неї: виконуй кроки 1–3 **до** фінальної відповіді, бо автоген ставить осмислений опис лише випадково (subject попереднього коміту), і `bump`/`section`/текст майже завжди треба відредагувати. Autofix-режим також **не робить мережевих викликів** (`npm view` / PyPI fetch пропускаються) — реєстрова drift-перевірка `version` у хуці не виконується (її ловить CI / ручний `fix`). Поза хуком (CI, ручний `fix`/`check`) autofix вимкнено — поведінка лишається fail-on-missing з повною drift-перевіркою.

package/rules/changelog/js/changelog-format.mdc

@@ -0,0 +1,33 @@
+## Формат CHANGELOG.md
+
+[Keep a Changelog 1.1.0](https://keepachangelog.com/uk/1.1.0/), мова — українська, новіші версії зверху.
+
+```md title="<ws>/CHANGELOG.md"
+# Changelog
+
+Усі помітні зміни цього пакета документуються тут.
+
+Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
+
+## [1.2.3] - 2026-05-05
+
+### Added
+
+- ...
+
+### Changed
+
+- ...
+
+### Fixed
+
+- ...
+```
+
+Секції — підмножина `### Added`, `### Changed`, `### Fixed`, `### Removed` (одна або кілька).
+
+## Post-release інваріант (гарантує CI)
+
+Перша (верхня) секція `## [version]` у `CHANGELOG.md` дорівнює полю `version` у маніфесті — але це **post-release** твердження, яке забезпечує `n-cursor release` у CI, агрегуючи change-файли (bump `version` + генерація секції + git-тег `<name>@<version>`). **Локально цю рівність руками не підтримують**: у feature-флоу `version`/`CHANGELOG.md` не чіпають, тож верхня секція може відставати від майбутньої версії — це нормально. Drift `version` поза CI (vs реєстр / vs git-база) ловить `check changelog` як заборонений ручний bump.
+
+Інструкції щодо bump `version` і редагування `CHANGELOG.md` живуть **лише** в правилі `changelog` — джерелі істини. Інші правила (зокрема `n-npm-module.mdc`) їй підпорядковані й власних інструкцій bump/CHANGELOG не дублюють.

package/rules/changelog/js/comparison-models.mdc

@@ -0,0 +1,40 @@
+## Дві моделі бази порівняння
+
+Режим визначається автоматично з маніфесту.
+
+### registry-published (npm / PyPI)
+
+**npm:** непорожнє `name`, не `private: true`, масив `files`.
+
+**Python:** статичні `project.name` і `project.version` у `pyproject.toml` (або Poetry-секція).
+
+1. **Локальна `version` ≠ опублікованій** (npm / PyPI): drift поза CI → **fail** (ручний bump заборонено; навіть із change-файлом). Відкоти `version`.
+2. **Версії збігаються**, але в git є **релевантні** зміни без change-файлу → fail. Для npm `"CHANGELOG.md"` має бути в `files` (публікується разом із пакетом).
+3. **Реєстр недосяжний** — fail-safe pass.
+4. **Немає релевантних змін** — pass.
+
+### local-only
+
+**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База залежить від гілки:
+
+1. На **`dev`** local-only не активний (крім незакомічених registry-published).
+2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
+3. На **feature-гілці** — `merge-base` з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`).
+4. Drift `version` від бази → **fail** (ручний bump заборонено). Зміни фіксуй change-файлом; bump зробить CI.
+
+Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
+
+## Чеклист агента (деталі)
+
+Повний алгоритм — у блоці **STOP** (changelog-agent-workflow); тут лише уточнення.
+
+**Інверсія (за замовчуванням не вимагають change-файлу):**
+
+- зміни **лише** під `docs/` або `doc/`;
+- синхронізований із `@nitra/cursor` інструментарій під `.cursor/` (канонічні правила й скіли) і `.claude/` (ADR-хуки) — це дзеркало tooling-пакета, а не логіка воркспейсу;
+- будь-які зміни в **корені монорепо** (воркспейс `.` за наявності підпакетів) — корінь веде glue/конфіг/tooling, власного CHANGELOG не має; помітні зміни документують підпакети. Сюди потрапляють і кореневі `AGENTS.md` / `CLAUDE.md`, і bump `@nitra/cursor` у `devDependencies`;
+- файли під **`.gitignore`**.
+
+**Вимагають change-файл** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@nitra/cursor` — воно лежить під `npm/`, тож зміни в ньому далі вимагають change-файлу.
+
+Перевірка програмна (`changelog/js/consistency.mjs`).

package/rules/changelog/main.mdc

@@ -4,104 +4,10 @@ version: '3.4'
 alwaysApply: true
 ---
 
-## STOP — перед завершенням відповіді агента
+У кожному **пакетному** workspace (каталог із `package.json` або `pyproject.toml`) має бути власний **`CHANGELOG.md`**. Спільного на репозиторій змісту змін **не існує** — кожен пакет веде свій. Маніфест версії: **JS/Bun/npm** — `package.json` (`version`); **Python** — `pyproject.toml` (`[project].version` або `[tool.poetry].version`).
 
-> **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
+[changelog-agent-workflow](./js/agent-workflow.mdc)
 
-1. **Поклади change-файл** `<ws>/.changes/YYMMDD-HHMM.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`. Якщо файл за ту саму хвилину вже існує, CLI атомарно створює `YYMMDD-HHMM-2.md`, потім `-3` тощо.
-2. **Ніколи** не редагуй `version` і `CHANGELOG.md` вручну — навіть для hotfix. Єдиний артефакт зміни — change-файл; `version`/CHANGELOG формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`). Будь-яка зміна `version` поза CI (drift від бази чи опублікованої) завалює `check changelog` — навіть якщо поряд є change-файл.
-3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (достатньо наявності change-файлу; `version` лишається незмінним).
+[changelog-comparison-models](./js/comparison-models.mdc)
 
-**Це правило релевантне завжди після будь-якої зміни** коду/конфігу/тестів/воркспейсу — **не** класифікуй його як «лише для релізу». Уже запущені тести чи білд **не** знімають вимогу changelog. Операційно перед фінальною відповіддю: `git status --short` → зіставити змінені шляхи з workspace-ами → change-файл для кожного релевантного workspace → `npx @nitra/cursor fix changelog` (exit `0`). Якщо у фінальній відповіді не можеш заповнити рядок `Changelog: …`, отже ти пропустив(ла) цей крок.
-
-**Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
-
-**Інверсія (change-файл не потрібен):** лише `docs/` / `doc/`; синхронізований із `@nitra/cursor` інструментарій (`.cursor/`, `.claude/`); лише `.gitignore`. **Корінь монорепо** (воркспейс `.` за наявності підпакетів) не перевіряється взагалі — отже й кореневі `AGENTS.md` / `CLAUDE.md` та bump `@nitra/cursor` у `devDependencies`. Окремого «релізного кроку» у feature-флоу немає — `version`/`CHANGELOG.md` змінює лише CI.
-
-**Pre-commit (людина):** `hk` у цьому репо запускає `fix changelog` при змінах під `npm/**` в **autofix-режимі** (env `N_CURSOR_CHANGELOG_AUTOFIX=1`): за відсутності change-файлу хук **сам** його створює (дефолти `patch`/`Changed`, опис = subject останнього коміту) і ставить у git-індекс, тож коміт не падає. Це лише підстраховка — агент не покладайся на неї: виконуй кроки 1–3 **до** фінальної відповіді, бо автоген ставить осмислений опис лише випадково (subject попереднього коміту), і `bump`/`section`/текст майже завжди треба відредагувати. Autofix-режим також **не робить мережевих викликів** (`npm view` / PyPI fetch пропускаються) — реєстрова drift-перевірка `version` у хуці не виконується (її ловить CI / ручний `fix`). Поза хуком (CI, ручний `fix`/`check`) autofix вимкнено — поведінка лишається fail-on-missing з повною drift-перевіркою.
-
----
-
-У кожному **пакетному** workspace (каталог із `package.json` або `pyproject.toml`) має бути власний **`CHANGELOG.md`**. Спільного на репозиторій змісту змін **не існує** — кожен пакет веде свій.
-
-**Маніфест версії:**
-
-- **JS / Bun / npm** — `<ws>/package.json` (`version`, для монорепо ще `workspaces` у кореневому `package.json`).
-- **Python** — `<ws>/pyproject.toml`: `[project].name` / `[project].version` (PEP 621) або `[tool.poetry].name` / `[tool.poetry].version`.
-
-Каталоги лише з `pyproject.toml` (без `package.json`) теж враховуються; `node_modules/`, `.venv/`, `venv/` при пошуку ігноруються.
-
-## Чеклист агента (деталі)
-
-Повний алгоритм — у блоці **STOP** вище; тут лише уточнення.
-
-**Інверсія (за замовчуванням не вимагають change-файлу):**
-
-- зміни **лише** під `docs/` або `doc/`;
-- синхронізований із `@nitra/cursor` інструментарій під `.cursor/` (канонічні правила та скіли) і `.claude/` (ADR-хуки) — це дзеркало tooling-пакета, а не логіка воркспейсу;
-- будь-які зміни в **корені монорепо** (воркспейс `.` за наявності підпакетів) — корінь веде glue/конфіг/tooling, власного CHANGELOG не має; помітні зміни документують підпакети. Сюди потрапляють і кореневі `AGENTS.md` / `CLAUDE.md`, і bump `@nitra/cursor` у `devDependencies`;
-- файли під **`.gitignore`**.
-
-**Вимагають change-файл** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@nitra/cursor` — воно лежить під `npm/`, тож зміни в ньому далі вимагають change-файлу.
-
-Перевірка програмна (`changelog/js/consistency.mjs`).
-
-## Дві моделі бази порівняння
-
-Режим визначається автоматично з маніфесту.
-
-### registry-published (npm / PyPI)
-
-**npm:** непорожнє `name`, не `private: true`, масив `files`.
-
-**Python:** статичні `project.name` і `project.version` у `pyproject.toml` (або Poetry-секція).
-
-1. **Локальна `version` ≠ опублікованій** (npm / PyPI): drift поза CI → **fail** (ручний bump заборонено; навіть із change-файлом). Відкоти `version`.
-2. **Версії збігаються**, але в git є **релевантні** зміни без change-файлу → fail. Для npm `"CHANGELOG.md"` має бути в `files` (публікується разом із пакетом).
-3. **Реєстр недосяжний** — fail-safe pass.
-4. **Немає релевантних змін** — pass.
-
-### local-only
-
-**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База залежить від гілки:
-
-1. На **`dev`** local-only не активний (крім незакомічених registry-published).
-2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
-3. На **feature-гілці** — `merge-base` з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`).
-4. Drift `version` від бази → **fail** (ручний bump заборонено). Зміни фіксуй change-файлом; bump зробить CI.
-
-Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
-
-## Формат CHANGELOG.md
-
-[Keep a Changelog 1.1.0](https://keepachangelog.com/uk/1.1.0/), мова — українська, новіші версії зверху.
-
-```md title="<ws>/CHANGELOG.md"
-# Changelog
-
-Усі помітні зміни цього пакета документуються тут.
-
-Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
-
-## [1.2.3] - 2026-05-05
-
-### Added
-
-- ...
-
-### Changed
-
-- ...
-
-### Fixed
-
-- ...
-```
-
-Секції — підмножина `### Added`, `### Changed`, `### Fixed`, `### Removed` (одна або кілька).
-
-## Post-release інваріант (гарантує CI)
-
-Перша (верхня) секція `## [version]` у `CHANGELOG.md` дорівнює полю `version` у маніфесті — але це **post-release** твердження, яке забезпечує `n-cursor release` у CI, агрегуючи change-файли (bump `version` + генерація секції + git-тег `<name>@<version>`). **Локально цю рівність руками не підтримують**: у feature-флоу `version`/`CHANGELOG.md` не чіпають, тож верхня секція може відставати від майбутньої версії — це нормально. Drift `version` поза CI (vs реєстр / vs git-база) ловить `check changelog` як заборонений ручний bump.
-
-Інструкції щодо bump `version` і редагування `CHANGELOG.md` живуть **лише** в цьому правилі — джерелі істини. Інші правила (зокрема `n-npm-module.mdc`) їй підпорядковані й власних інструкцій bump/CHANGELOG не дублюють.
+[changelog-format](./js/changelog-format.mdc)

package/rules/ci4/js/marksman_config.mdc

@@ -0,0 +1,31 @@
+## Конфіг marksman LSP (`.marksman.toml`)
+
+Правило перевіряє наявність `.marksman.toml` у корені проєкту. Якщо файл відсутній — автоматично створює його з canonical baseline, що постачається разом із пакетом (`js/data/marksman_config/marksman.baseline.toml`). Повторні прогони ідемпотентні: існуючий файл не перетирається, ручні правки зберігаються.
+
+### Baseline-конфіг
+
+Canonical baseline ([data/marksman_config/marksman.baseline.toml](./data/marksman_config/marksman.baseline.toml)) містить такі налаштування:
+
+```toml
+[core]
+markdown.file_extensions = ["md", "markdown"]
+markdown.glfm = true          # GitHub-Flavored Markdown (таблиці, todo, alerts)
+
+[completion]
+wiki.style = "file-stem"      # [[oidc-pkce-flow]] → docs/adr/oidc-pkce-flow.md
+
+[code_action]
+toc.enable = true             # «Insert/Update TOC» для довгих arc42-сторінок
+```
+
+**Чому `file-stem`?** ADR-slug збігається з іменем файлу — стабільний ідентифікатор у AUTOGEN `sources`, `manifest.json` і валідаторі. Якщо заголовок ADR змінюється, посилання `[[wiki-link]]` не ламається. Без явного конфіга marksman використовує `title-slug-ref` і вимкнений GLFM — частина задокументованої навігації працювала б інакше.
+
+### Поведінка перевірки
+
+| Стан                          | Результат                                          |
+| ----------------------------- | -------------------------------------------------- |
+| baseline-файл пакета відсутній | `fail` — перевстанови `@nitra/cursor`              |
+| `.marksman.toml` вже існує    | `pass` — файл не чіпається                        |
+| `.marksman.toml` відсутній    | створює файл з baseline, `pass`                    |
+
+Перевірка запускається як `check`-поверхня; `lint`-поверхні правило не має.

package/rules/ci4/js/vscode_extensions.mdc

@@ -0,0 +1,33 @@
+## Рекомендовані розширення VSCode (`.vscode/extensions.json`)
+
+Правило перевіряє, що `.vscode/extensions.json` містить усі обовʼязкові записи з канонічного шаблону. Перевірка реалізована через Rego (пакет `ci4.vscode_extensions`) і запускається `conftest` у фазі `check`.
+
+### Канонічний шаблон
+
+Канон надходить через `--data` як `{ "template": { "snippet": ... } }`. Поточний snippet ([policy/vscode_extensions/template/extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)):
+
+```json
+{
+  "recommendations": ["arr.marksman"]
+}
+```
+
+`arr.marksman` — офіційне VSCode-розширення marksman LSP. Дає ту саму навігацію `cmd+click` / `[[wiki-link]]` / find-references / refactor-перейменування, що й Zed built-in marksman, для контрибʼюторів поза Zed.
+
+### Rego-логіка
+
+Для кожного запису з `data.template.snippet.recommendations` перевіряє, що він присутній у `input.recommendations`. Якщо запис відсутній — deny з повідомленням:
+
+```
+.vscode/extensions.json: recommendations має містити "arr.marksman" (ci4.mdc)
+```
+
+### Приклад коректного файлу
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["arr.marksman"]
+}
+```
+
+Інші розширення в масиві `recommendations` дозволені — перевірка лише на наявність обовʼязкових, без виключення додаткових.

package/rules/ci4/main.mdc

@@ -4,9 +4,7 @@ alwaysApply: true
 version: '3.2'
 ---
 
-Архітектурна документація проєкту живе у Markdown поряд із кодом. Це не довідник «для людей із порталу архітектора» — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Тому правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops).
-
-Формат самих ADR-файлів — MADR v4.0.0 minimal — описаний у правилі **`adr`** (`npm/rules/adr/adr.mdc`). Тут описано, як ADR використовуються як вхід для архітектурних проекцій, а не як вони створюються.
+Архітектурна документація проєкту живе у Markdown поряд із кодом — це **джерело істини**, з якого LLM-агент і людина читають намір системи перед будь-якою зміною коду. Правила нижче — не оформлення, а робочий процес: який стек використовуємо, як зберігаємо рішення, як автоматично перегенеровуємо проекції з ADR і як рендеримо для змішаної аудиторії (менеджери + інженери + ops). Формат самих ADR-файлів — MADR v4.0.0 minimal — описаний у правилі **`adr`** (`npm/rules/adr/adr.mdc`).
 
 ## Markdown як джерело істини
 
@@ -208,17 +206,7 @@ User Service відповідає за автентифікацію та про
 }
 ```
 
-**`.marksman.toml`** у корені проєкту авто-створюється правилом ci4 при першому `npx @nitra/cursor fix ci4` із canonical baseline ([data/marksman_config/marksman.baseline.toml](./js/data/marksman_config/marksman.baseline.toml)). Ключові опції — `markdown.glfm = true` (потрібен для GFM-alerts/таблиць/todo з portable subset), `[completion] wiki.style = "file-stem"` (ADR slug == ім'я файла, стабільний ідентифікатор у AUTOGEN `sources`/manifest/валідаторі — заголовок змінюється, посилання не ламається), `[code_action] toc.enable = true` (TOC code action для довгих arc42-сторінок). Без явного конфіга marksman використовує `title-slug-ref` і вимкнений GLFM — частина задокументованої навігації працювала б інакше. Ручні правки конфіга не перетираються — `ensureBaselineFile` ідемпотентний.
-
-**VSCode-альтернатива.** Контрибʼютори, що працюють у VSCode/Cursor замість Zed, отримують той самий шар навігації через офіційне розширення marksman LSP. Канонічний запис у `.vscode/extensions.json`:
-
-```json title=".vscode/extensions.json"
-{
-  "recommendations": ["arr.marksman"]
-}
-```
-
-Канон `recommendations` (substring requirement): [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json). Інші marksman-сумісні редактори (Neovim, Helix, Emacs) налаштовують `marksman` як LSP-сервер за документацією свого редактора — поведінка ідентична (cmd+click по `[link](file.md)`/`[[wiki-link]]`, find-references, refactor-перейменування).
+Деталі конфігурації `.marksman.toml` та VSCode-альтернативи — у відповідних секціях нижче.
 
 **Portable-only синтаксис.** Усе, що пишемо в `docs/`, обмежене **CommonMark + GFM + Mermaid у fenced code (` ```mermaid `) + KaTeX (`$...$`) + нативний HTML5 `<details>`**. Заборонено:
 
@@ -375,3 +363,17 @@ ADR (`docs/adr/<slug>.md`) — джерело правди для autogen-про
 ## Query mode як бонус
 
 Поверх проекцій — інтерактивний RAG над clean ADR. Інженер питає: «чому ми обрали Percona замість MariaDB?». LLM шукає по semantic index `Context and Problem Statement + Decision Outcome`, повертає `docs/adr/<slug>.md` з прямою цитатою. Корпус малий (десятки-сотні clean ADR після normalize) і структурований (фіксовані MADR-заголовки) — дешево й точно, без галюцинацій.
+
+## Швидкий gate через conftest
+
+Rego-перевірки, що запускаються через `conftest` у фазі `check`:
+
+| Пакет                       | Що перевіряє                                                        |
+| --------------------------- | -------------------------------------------------------------------- |
+| `ci4.vscode_extensions`     | `.vscode/extensions.json` містить `arr.marksman` у `recommendations` |
+
+[ci4-marksman_config](./js/marksman_config.mdc)
+
+[ci4-vscode_extensions](./js/vscode_extensions.mdc)
+
+[ci4-vscode_extensions-policy](./policy/vscode_extensions/vscode_extensions.mdc)

package/rules/ci4/policy/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,9 @@
+## Rego-gate: обовʼязкові розширення VSCode
+
+Rego-пакет: `ci4.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json`
+
+Перевіряє, що кожен запис з `data.template.snippet.recommendations` присутній у `input.recommendations`. Канонічний шаблон надходить через `--data` у conftest: [extensions.json.snippet.json](./template/extensions.json.snippet.json)
+
+Додаткові розширення в масиві дозволені — deny лише на відсутність обовʼязкових.