@7n/rules 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [1.7.1] - 2026-07-16
+
+### Fixed
+
+- vue: відновлено втрачений guide-контент (composition-api, quasar-ui, structure, testing, tfm, vite-config, vite-env, nheader-layout) + виправлено застарілий шлях у main.mdc
+- restore: відновлено втрачений guide-контент для 21 правила з коміту da05f89d (docs-only guide/ concern-и), виправлено застарілі шляхи в abie/ga/php/python
+- rules: розкладено docs-only guide/ по всіх 22 правилах на окремі per-concern директорії, реалізовано реальні check/policy де це мало сенс (vue tfm-translations, capacitor workspace:*, k8s hpa apiVersion, style admin-table/gap/quasar-fixes, tauri tool_surface), решту залишено docs-only зі звітом де check недоцільний
+
 ## [1.7.0] - 2026-07-16
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/abie/http_route_base/http_route_base.mdc

@@ -6,4 +6,26 @@ Rego-пакет: `abie.http_route_base`
 
 Перевіряє, що кожен hostname у `spec.hostnames` належить до домену `aiml.live`: точна відповідність `aiml.live`, wildcard `*.aiml.live` або будь-який піддомен `*.aiml.live`. Перевірка case-insensitive. Не є HTTPRoute — пакет не діє.
 
-JS-частина (cross-file аналіз ua-overlay, backendRefs, тощо) — у `js/ua_http_route.mjs`. Людинозрозумілий опис + приклади — у `js/http_route_base.mdc`.
+JS-частина (cross-file аналіз ua-overlay, backendRefs, тощо) — у `ua_http_route/main.mjs`.
+
+### Приклади
+
+```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/adr/madr_format/concern.json

@@ -0,0 +1 @@
+{"$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"}

package/rules/adr/madr_format/madr_format.mdc

@@ -0,0 +1,119 @@
+## 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 не містить альтернатив або підтверджених наслідків, LLM-промпт нормалізатора вимагає явно писати `Інші варіанти в transcript не обговорювалися.` або `transcript не містить підтвердження ...`, а не вигадувати відсутні факти.
+
+Є два стани файлу, які відрізняються YAML frontmatter:
+
+- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYMMDD-HHMM-<sid>.md` (fallback на старі чернетки без розпізнаного heading). Пише `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`); підтримуються і старіші чернетки з `YYYYMMDD-HHMMSS-` prefix. Створений руками clean-файл може мати просто `<slug>.md`.
+
+`normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
+
+**Примітка про історичні файли:** описаний тут MADR v4 minimal — конвенція для файлів, які проходять актуальну версію `normalize-decisions.sh`. Каталог `docs/adr/` цього ж репозиторію містить і файли зі старішими форматами frontmatter/заголовків (напр. `type: ADR` + `topic:`/`spec:` без `title:`, чи заголовки українською на кшталт «Контекст»/«Рішення»), накопичені до впровадження поточної конвенції. Тому автоматизованої перевірки форми clean-ADR тут немає — рекурсивна класифікація "старий/новий формат" по вмісту ненадійна, а lint по всіх файлах масово провалював би легітимні історичні записи.
+
+## Фаза 1 — Capture
+
+Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM-бекенд з evidence-bound промптом і записує результат у **`docs/adr/<timestamp>-<slug-або-sid>.md`**, якщо модель повернула MADR-блок з шапкою `## ...`. Якщо модель повернула `NONE` (тривіальна сесія) або відповідь порожня — нічого не пишеться. Slug для імені файлу виводиться локально (без додаткового LLM-виклику) з першого `## `-заголовка відповіді. Рекурсію з внутрішнього виклику моделі блокує 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`.
+
+Вибір LLM-бекенду для Capture (`CAPTURE_DECISIONS_BACKEND`, дефолт `pi`) описаний окремо в `adr/main.mdc` ("Capture-бекенд"), тут не дублюється.
+
+**Cross-project skip:** якщо в сесії редагувалися файли, але жоден не під поточним `PROJECT_ROOT` — це паралельна робота в іншому проєкті, і ADR-чернетка не пишеться (сесії без жодних редагувань, тобто чисте Q&A, цей гейт не відкидає). Вимикається `ADR_CAPTURE_SKIP_CROSS_PROJECT=0`.
+
+**Tooling-only skip:** перед викликом LLM `capture-decisions.sh` дивиться у transcript на `tool_use`-правки (`Edit`/`Write`/`MultiEdit`). Якщо всі змінені файли потрапляють у вузький allowlist — `.cspell.json`, `docs/adr/*.md`, `CHANGELOG.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` (той самий прапор ділять capture і normalize).
+
+## Фаза 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` / `CHERRY_PICK_HEAD` / `REVERT_HEAD` / `rebase-apply` / `rebase-merge` — небезпечно правити файли посеред конфлікту чи rebase.
+- Виходить миттєво, якщо інший normalize-запуск тримає `flock` на `.claude/hooks/.normalize.lock` (тільки де `flock` доступний — macOS без нього просто не блокує паралельний запуск).
+- Перед викликом LLM для кожної чернетки batch'а читає `transcript:` із frontmatter і той самий tool_use-список. Чернетки tooling-only — видаляє без виклику LLM. Якщо після фільтра batch порожній — `exit 0`.
+
+LLM повертає масив операцій:
+
+| `op` | Семантика | Поля |
+| --- | --- | --- |
+| `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
+| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: draft-frontmatter (`session:`/`captured:`/`transcript:`) заміняється на OKF v0.1 (`type: ADR`, `title:`), ім'я → `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено), додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. Якщо LLM не повернула OKF frontmatter, скрипт сам дописує мінімальне (`type: ADR`, `title:` з першого `# `-рядка або зі `slug`). | `file`, `slug`, `content` |
+| `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. Скрипт резолвить `target` у три кроки: точна назва в `docs/adr/`, slug свіжо створеного `rewrite` цього ж батчу, або унікальний існуючий файл, що закінчується на `-<slug>.md`. | `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-виклик, який запустить normalize, успадковує `ADR_NORMALIZE_RUNNING=1` — внутрішній Stop-hook вийде відразу. `ADR_HOOKS_SKIP=1` (виставляє JS-оркестратор перед `npx @7n/rules lint`/`/n-lint`/`/n-doc-files`/`/n-taze` тощо) також блокує запуск раніше за ці guard'и — деталі в `adr/main.mdc`. Доступні ENV для нормалізації:
+
+| Змінна | Default | Призначення |
+| --- | --- | --- |
+| `ADR_NORMALIZE_THRESHOLD` | `30` | Поріг чернеток для запуску фази. |
+| `ADR_NORMALIZE_BATCH` | `10` | Максимум чернеток у одному виклику LLM. |
+| `ADR_NORMALIZE_MIN_INTERVAL_HOURS` | `6` | Мінімум між спробами (навіть якщо поріг). |
+| `ADR_NORMALIZE_DRY` | `0` | `1` — лише лог запланованих операцій, без змін на диску. |
+| `ADR_NORMALIZE_BACKEND` | автовизначення | `local`/`pi`/`claude`/`cursor` — примусовий вибір бекенду (див. нижче). |
+| `ADR_NORMALIZE_MODEL` | `sonnet` | Модель для бекенду `claude`. |
+| `ADR_NORMALIZE_CURSOR_MODEL` | `claude-4.6-sonnet-medium` | Модель для бекенду `cursor`. |
+| `ADR_NORMALIZE_PI_MODEL` | `$N_CLOUD_AVG_MODEL` (fallback `openai-codex/gpt-5.5`) | Модель для бекенду `pi`. |
+| `ADR_NORMALIZE_LOCAL_CMD` | `npx --no @7n/rules adr-normalize-local` | Команда локального пайплайна (override для тестів/in-repo). |
+| `ADR_NORMALIZE_SKIP_TOOLING_ONLY` | `1` | `0` — вимкнути structural skip tooling-only сесій (той самий прапор ділять capture і normalize). |
+
+Для ручного запуску (поза порогом і поза Stop-хуком) є **`/n-adr-normalize`** — slash-команда тимчасово виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0` та викликає скрипт напряму.
+
+## Normalize LLM-бекенд: local → pi → claude → cursor
+
+`ADR_NORMALIZE_BACKEND` (якщо не заданий явно) обирається автоматично:
+
+1. **`local`** — якщо задано `N_LOCAL_MIN_MODEL`: конвеєр на малій локальній моделі (privacy + $0, `npm/scripts/lib/adr/normalize-pipeline.mjs`, викликається через `ADR_NORMALIZE_LOCAL_CMD`) сам будує дрібні промпти з батча.
+2. **`pi`** — якщо `pi` є в `PATH`: `pi -p --model "$ADR_NORMALIZE_PI_MODEL" --no-prompt-templates`.
+3. **`claude`** — якщо `claude` є в `PATH`: `claude -p --model "$ADR_NORMALIZE_MODEL"`.
+4. **`cursor`** — якщо `cursor-agent` є в `PATH`: `cursor-agent -p --mode ask --output-format text --model "$ADR_NORMALIZE_CURSOR_MODEL"`.
+5. Жодного бекенду — скрипт логує `no LLM backend available` і виходить з кодом `0` без змін.
+
+Вибір LLM-бекенду для Capture (`CAPTURE_DECISIONS_BACKEND`: `pi`/`claude`/`cursor-agent`/`auto`, дефолт `pi`) — окремий механізм, задокументований в `adr/main.mdc`.
+
+## Структура каталогу
+
+```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 @7n/rules`, коли правило `adr` увімкнене):
+
+```gitignore
+node_modules/
+dist/
+*.secret
+
+# @7n/rules (adr) — локальні артефакти Stop-hook, не коміти
+.claude/hooks/*.log
+.claude/hooks/.normalize-state
+.claude/hooks/.normalize.lock
+.claude/scheduled_tasks.lock
+```

package/rules/bun/bunfig/bunfig.mdc

@@ -10,3 +10,8 @@ Gate порівнює кожен leaf-ключ у кожній секції ша
 
 - секція відсутня або не є обʼєктом (`bunfig.toml: відсутня секція [install]`)
 - leaf-ключ має інше значення (`bunfig.toml: у секції [install] має бути linker = "hoisted"`)
+
+## Навіщо саме `linker = "hoisted"`
+
+Канонічна лінковка для кореневого `bunfig.toml` — **hoisted**: пласке `node_modules`,
+сумісне з інструментами, які не розуміють ізольований (isolated) layout Bun.

package/rules/bun/lint-surface/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/bun/lint-surface/lint-surface.mdc

@@ -0,0 +1,13 @@
+## Лінт через n-rules, не package.json-скрипти
+
+Лінт запускається через CLI **`n-rules`** (локально) / **`npx @7n/rules`** (без локальної інсталяції),
+**не** через `package.json`-скрипти:
+
+- **`npx @7n/rules lint --full`** — весь репо (CI-режим);
+- **`npx @7n/rules lint`** — дельта vs origin (лише змінені файли, типовий задачний прогін);
+- **`n-rules lint <rule…>`** — конкретні правила, напр. **`n-rules lint ga`**.
+
+У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI
+`n-rules` (пакет `@7n/rules`). Цей запис механічно перевіряється Rego-gate'ом
+[`bun.package_json`](../package_json/package_json.mdc) (deny на `scripts.lint` / `scripts.lint-*`) —
+тут лишається лише пояснення *чому* так (єдина точка входу для лінту), без дублювання самого чеку.

package/rules/capacitor/platforms/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/capacitor/platforms/main.mjs
 docgen:
-  crc: a25bb28b
+  crc: c3537051
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 95
 ---

package/rules/capacitor/platforms/main.mjs

@@ -74,7 +74,8 @@ const RE_COCOAPODS_EXEMPT_ALLOW = /\biosCocoaPodsAllowed\s*:\s*true\b/
 /**
  * Мінімальний **major** (нижня межа) для **однієї** OR-частини діапазону npm (без `||` всередині).
  * @param {string} segment одна частина після `||` або весь рядок
- * @returns {number | null} null, якщо **`*` / `x` / `latest`**, або **major** **нижньої** межі
+ * @returns {number | null} `Infinity`, якщо **`workspace:`**-протокол (завжди прийнятний, як у Rego-gate
+ *   `capacitor.package_json`); `null`, якщо **`*` / `x` / `latest`**, або **major** **нижньої** межі
  */
 export function capacitorSegmentMinMajor(segment) {
   if (typeof segment !== 'string') {
@@ -85,6 +86,9 @@ export function capacitorSegmentMinMajor(segment) {
     return null
   }
   const low = s0.toLowerCase()
+  if (low.startsWith('workspace:')) {
+    return Infinity
+  }
   if (s0 === '*' || low === 'x' || low === 'latest') {
     return null
   }

package/rules/capacitor/platforms/platforms.mdc

@@ -0,0 +1,108 @@
+## JS-перевірка: версія Capacitor та iOS SPM/CocoaPods
+
+JS-модуль: `platforms/main.mjs` (authoritative check, `capacitor.mdc`) — обходить усі `package.json`
+у дереві та iOS-шар (`Podfile`) одним проходом.
+
+### Версія `@capacitor/core`
+
+У `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:*` (і будь-який інший діапазон із префіксом `workspace:`) — **завжди прийнятний**
+(як у Rego-gate `capacitor.package_json`): реальна версія походить від workspace-пакета, який
+перевіряється окремо. `*` / `x` / `latest` (без префікса `workspace:`) — **неприйнятні**: діапазон
+не гарантує мажор ≥ 8.
+
+**Приклади допустимих діапазонів:**
+
+```
+"@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 — неприйнятна
+```
+
+### 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/changelog/consistency/comparison-models.mdc

@@ -0,0 +1,46 @@
+## Дві моделі бази порівняння
+
+Режим визначається автоматично з маніфесту.
+
+### 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`). За наявності `origin/*` беремо новішу з двох баз (локальна гілка-кандидат vs `origin/`-версія) — застарілий локальний `main`/`dev` не має перекривати вже інтегровану в origin історію, і навпаки.
+4. Drift `version` від бази → **fail** (ручний bump заборонено). Зміни фіксуй change-файлом; bump зробить CI.
+
+Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
+
+Merge-коміт (готовий, з другим предком, або `MERGE_HEAD` під час незавершеного `git commit`) пропускається цілком — changeset документують feature-коміти, а не інтеграційний merge.
+
+## Чеклист агента (деталі)
+
+Основний робочий алгоритм — «перед фінальною відповіддю виконай `npx @7n/rules lint changelog`, познач результат рядком `Changelog: …`» (AGENTS.md/AGENTS.template.md); тут лише уточнення, що саме перевіряється.
+
+**Інверсія (за замовчуванням не вимагають change-файлу):**
+
+- зміни **лише** під `docs/` або `doc/`;
+- синхронізований із `@7n/rules` інструментарій під `.cursor/` (канонічні правила й скіли) і `.claude/` (ADR-хуки) — це дзеркало tooling-пакета, а не логіка воркспейсу;
+- будь-які зміни в **корені монорепо** (воркспейс `.` за наявності підпакетів) — корінь веде glue/конфіг/tooling, власного CHANGELOG не має; помітні зміни документують підпакети. Сюди потрапляють і кореневі `AGENTS.md` / `CLAUDE.md`, і bump `@7n/rules` у `devDependencies`;
+- файли під **`.gitignore`**.
+
+**Вимагають change-файл** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@7n/rules` — воно лежить під `npm/`, тож зміни в ньому далі вимагають change-файлу.
+
+Ніколи не редагуй `version` і `CHANGELOG.md` вручну — навіть для hotfix; єдиний артефакт зміни — change-файл (`npx @7n/n ch [--bump <major|minor|patch>] [--section <Added|Changed|Fixed|Removed>] [--message "<…>"]`), bump/секцію CHANGELOG формує `n-rules release` у CI на `main`.
+
+Канонічне pre-commit wiring (крок `npm-changelog` у `hk.pkl`, autofix через `N_RULES_CHANGELOG_AUTOFIX=1`) — деталь `npm-module.mdc`, тут не дублюється.
+
+Перевірка програмна (`changelog/consistency/main.mjs`, delta-гейт присутності — `changelog/presence/main.mjs`).

package/rules/changelog/consistency/consistency.mdc

@@ -0,0 +1,35 @@
+## Формат 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` (одна або кілька).
+
+Механічно `main.mjs` (`checkChangelogFormat`) перевіряє лише наявність рядка `# Changelog` (H1). Точна лексика секцій і порядок версій (новіші зверху) — конвенція, яку check **не** валідує: наявні `CHANGELOG.md` у цьому репо містять і нестандартні секції (`### BREAKING`, `### Notes`, `### TODO` тощо) з історичних причин, тож строга валідація словника секцій зробила б check несумісним із власною практикою репо. Дотримання — на розсуд автора change-файлу.
+
+## Post-release інваріант (гарантує CI)
+
+Перша (верхня) секція `## [version]` у `CHANGELOG.md` дорівнює полю `version` у маніфесті — але це **post-release** твердження, яке забезпечує `n-rules release` у CI, агрегуючи change-файли (bump `version` + генерація секції + git-тег `<name>@<version>`). **Локально цю рівність руками не підтримують**: у feature-флоу `version`/`CHANGELOG.md` не чіпають, тож верхня секція може відставати від майбутньої версії — це нормально. Drift `version` поза CI (vs реєстр / vs git-база) ловить цей concern (`consistency`) як заборонений ручний bump.
+
+Інструкції щодо bump `version` і редагування `CHANGELOG.md` живуть **лише** в правилі `changelog` (деталізація моделі порівняння — `comparison-models.mdc` поряд) — джерелі істини. Інші правила (зокрема `npm-module`) їй підпорядковані щодо формату/моделі й власних інструкцій bump/CHANGELOG не дублюють; команду створення change-файлу (`npx @7n/n ch`) й заборону ручного bump вони лише повторюють як нагадування.