@nitra/cursor 1.8.173 → 1.8.177

package/.claude-template/npm-CLAUDE.md

@@ -4,20 +4,25 @@
 
 Path-scoped нагадування для агента: підвантажується автоматично, коли редагуємо файли під `npm/`.
 
-## Перед коміт-релевантними змінами в `npm/`
+## Перед PR з коміт-релевантними змінами в `npm/`
 
 1. Підвищ `version` у `npm/package.json` (build-bump, не більше одного кроку відносно `HEAD`).
 2. Додай запис у `npm/CHANGELOG.md` форматом Keep a Changelog: `## [версія] - YYYY-MM-DD` + секції `### Added/Changed/Fixed/Removed`.
+3. Переконайся, що `"CHANGELOG.md"` є в масиві `files` у `npm/package.json` (правило `changelog`).
 
-Без обох пунктів `npx @nitra/cursor check npm-module` падає, а `Stop` hook блокує завершення ходу.
+Логіка PR-scoped: bump і запис достатньо зробити **один раз — як суму по всьому PR** (порівняння йде з гілкою `dev`), а не на кожен коміт.
+
+Без оновленого CHANGELOG `npx @nitra/cursor check changelog` падає, а `Stop` hook блокує завершення ходу.
 
 ## Перевірка локально
 
 ```bash
+npx @nitra/cursor check changelog
 npx @nitra/cursor check npm-module
 ```
 
 ## Джерело правил
 
-- `.cursor/rules/n-npm-module.mdc` — повний текст правила
-- `npm/scripts/check-npm-module.mjs` — алгоритм перевірки
+- `.cursor/rules/n-changelog.mdc` — правило про CHANGELOG (PR-scoped, для всіх воркспейсів)
+- `.cursor/rules/n-npm-module.mdc` — правило публікації пакета (типи, hk, npm-publish workflow)
+- `npm/scripts/check-changelog.mjs`, `npm/scripts/check-npm-module.mjs` — алгоритми перевірки

package/CHANGELOG.md

@@ -4,7 +4,36 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
-## [1.8.173] - 2026-05-04
+## [1.8.177] - 2026-05-05
+
+### Changed
+
+- `changelog` (mdc v2.0): тепер дві моделі бази порівняння на рівні воркспейсу. **npm-published** (`name` + `files` + не `private: true`) — порівняння з опублікованою версією через `npm view <name> version` (git не задіяний; покриває кейс прямих комітів у `main` поза PR-flow). **local-only** (приватні / без `files`) — PR-scoped через `git merge-base <dev> HEAD`, що коректно обробляє: feature-гілку (видно лише унікальні коміти), `main` після merge `dev → main` (diff порожній → правило мовчить), direct-commit на `main` поза PR (ловиться як зміна, що потребує bump). Якщо реєстр недосяжний (офлайн / пакет не публікувався) — fail-safe pass, щоб локальна розробка не блокувалась.
+- `check-changelog.mjs`: повний рефактор. Експорт `check(opts?)` з опційним `getPublishedVersion` для підстановки в тестах (CLI калить без аргументів — використовується дефолтний `npm view`-виклик з 10s таймаутом). Класифікація воркспейсів через `isNpmPublishable(pkg)`; для published — `checkPublishedWorkspace`, для local-only — окрема `runLocalOnlyChecks` із власною skip-логікою (no-git / on dev / no dev ref / no merge-base) і `resolveMergeBase(baseRef)` через `git merge-base`. Спільна `verifyChangelogEntry` для обох режимів.
+- `n-changelog.mdc` / `mdc/changelog.mdc` (v1.1 → 2.0): переписано під дві моделі з прикладами кейсів.
+- Тести `check-changelog.test.mjs`: 16 кейсів (раніше 11) — npm-mode (sync / out-of-sync / no CHANGELOG / no entry / files без `CHANGELOG.md` / offline), local-only skip-логіка, merge-base сценарії (feature-гілка, `main` після merge `dev → main`, direct-commit на `main`), змішаний режим.
+
+## [1.8.176] - 2026-05-05
+
+### Changed
+
+- `changelog` стало єдиним правилом про CHANGELOG для всіх воркспейсів — включно з `npm/`. У `check-npm-module.mjs` прибрано `checkChangelog()` (і константу `CHANGELOG_PATH`); відповідну секцію `## CHANGELOG` видалено з `mdc/npm-module.mdc` (v1.9). Логіка перевірки `npm/CHANGELOG.md` лишилася незмінна за наповненням, але тепер вона PR-scoped (порівняння з `dev`), тож на feature-гілці bump і запис достатньо зробити **один раз — як суму по PR**, без bump-шуму в проміжних комітах.
+- `check-changelog.mjs`: додано перевірку `files`-масиву — якщо `<ws>/package.json` його оголошує, у ньому має бути `"CHANGELOG.md"` (приватні воркспейси без `files` цей пункт пропускають). Прибрано `SKIP_WORKSPACE = 'npm'` — `npm/` тепер у звичайному циклі. Хелпер `readPackageJsonOrNull` об'єднує читання `package.json` (раніше було два окремі читачі — `version` і `files`).
+- `auto-rules.mjs` / `auto-rules.md`: `changelog` переведено на `AUTO_RULE_DEPENDENCIES = ['bun']` (раніше — пряма умова `packageJsonExists`); тепер послідовно з рештою правил.
+- `npm/.claude-template/npm-CLAUDE.md` (і згенерований `npm/CLAUDE.md`): оновлено — посилається на `n-changelog.mdc`, явно згадує `files: ["CHANGELOG.md"]`, наголошує на PR-scoped логіці.
+- Тести `check-changelog.test.mjs`: кейс `npm/ пропускається` замінено на `npm/ перевіряється з files=["CHANGELOG.md"]`; додано окремий кейс fail при `files` без `CHANGELOG.md`.
+
+## [1.8.175] - 2026-05-05
+
+### Added
+
+- `k8s.mdc` / `check-k8s.mjs`: у маршрутах Gateway API (**HTTPRoute**, **GRPCRoute**, **TCPRoute**, **TLSRoute**, **UDPRoute**, група `gateway.networking.k8s.io`) забороняється поле `namespace` у `spec.rules[*].backendRefs[*]` (і однини `backendRef`), якщо його значення збігається з `metadata.namespace` самого маршруту. За замовчуванням Gateway API резолвить backend у тому ж namespace, що й маршрут — дублювання у `backendRef` мертве й заважає Kustomize-overlay, що міняє namespace маршруту. Cross-namespace backendRef (з відмінним `namespace`) правило не торкається. Експортовано `collectGatewayApiRouteBackendRefsWithRedundantNamespace(spec, routeNs)`; перевіряється усередині існуючого `failIfGatewayRouteUsesNonHeadlessService` (той самий обхід дерева, що й для headless-перевірки). Додано приклад «погано/добре» у `k8s.mdc` і відповідні юніт-тести.
+
+## [1.8.174] - 2026-05-05
+
+### Added
+
+- Нове правило `changelog` (`mdc/changelog.mdc` + `scripts/check-changelog.mjs`): для «звичайних» Bun-монорепо проєктів вимагає, щоб у кожному workspace, який змінився відносно базової гілки `dev`, у поточному PR було підвищено `version` у `<ws>/package.json` і додано запис `## [version] - YYYY-MM-DD` у `<ws>/CHANGELOG.md` (Keep a Changelog 1.1.0). Перевірка PR-scoped: на самій гілці `dev` пропускається; на feature-гілці bump і запис достатньо зробити **один раз — як суму по всьому PR**, без бамп-шуму в проміжних комітах. Воркспейс `npm/` пропускається — його CHANGELOG покриває окреме правило `npm-module`. У `auto-rules.md` / `auto-rules.mjs` `changelog` додано до автодетекту з умовою «у корені є `package.json`» і до `AUTO_RULE_ORDER` між `capacitor` і `docker`.
 
 ### Added
 

package/bin/auto-rules.md

@@ -12,6 +12,8 @@ bun - якщо в корені проекту є package.json
 
 capacitor - якщо в проекті є хоч один файл capacitor.config.json
 
+changelog - [bun]
+
 docker - якщо в проекті є хоч один Dockerfile
 
 ga - якщо присутня директорія .github/workflows

package/mdc/changelog.mdc

@@ -0,0 +1,64 @@
+---
+description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння
+alwaysApply: true
+version: '2.0'
+---
+
+Bun monorepo: у кожному workspace із кореневого `package.json.workspaces` (плюс кореневий пакет, плюс `npm/`) має бути власний **`CHANGELOG.md`**. Спільного на репозиторій змісту змін **не існує** — кожен пакет веде свій. Правило `npm-module` відповідає лише за публікацію типів і workflow, а CHANGELOG — за цим правилом.
+
+## Дві моделі бази порівняння
+
+Правило за **`<ws>/package.json`** автоматично визначає режим перевірки:
+
+### npm-published воркспейс
+
+Якщо в `<ws>/package.json` є непорожнє `name`, **не** `private: true` і оголошено масив `files` — workspace публікується в npm. База — **опублікована версія в реєстрі** (`npm view <name> version`):
+
+1. Якщо локальна `version` дорівнює опублікованій — ще нічого не зрелізнуто, перевірка мовчить.
+2. Якщо локальна `version` відрізняється від опублікованої — потрібен запис у `<ws>/CHANGELOG.md` для локальної версії (формат `## [версія] - YYYY-MM-DD`) і `"CHANGELOG.md"` у `files`.
+3. Якщо реєстр недосяжний (офлайн / пакет ще не публікувався) — fail-safe pass із поясненням, щоб локальна розробка не блокувалася.
+
+Git у цьому режимі не використовується — порівнюється поточний стан робочої копії з тим, що насправді в npm. Це покриває кейс «прямі коміти в `main` поза PR-flow» автоматично, бо неопубліковані зміни одразу видно.
+
+### local-only воркспейс
+
+Якщо workspace приватний (`private: true`) або без `files` (apps, services, internal-only пакети) — база = **гілка `dev`**, точніше `git merge-base <dev> HEAD`:
+
+1. На самій гілці `dev` правило не активне.
+2. На feature-гілці merge-base = точка розгалуження від `dev` → видно лише унікальні коміти цієї гілки. Bump + запис у `CHANGELOG.md` потрібні **раз на весь PR — як сума по гілці**, без bump-шуму в проміжних комітах.
+3. На `main` після merge `dev → main` merge-base = поточний `dev` → diff порожній → правило мовчить.
+4. Direct-commit на `main` поза PR-flow ловиться як зміна, що потребує bump + запис у `CHANGELOG.md`.
+
+Якщо не git-репо, або `dev`/`origin/dev` не існує — 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` (одна або кілька).
+
+## Перевірка
+
+`npx @nitra/cursor check changelog`

package/mdc/k8s.mdc

@@ -214,6 +214,41 @@ spec:
 
 **Точні умови та повідомлення `fail`** — верхній JSDoc **`npm/scripts/check-k8s.mjs`**.
 
+### Gateway API: не дублюй namespace у `backendRef`
+
+У маршрутах Gateway API (**HTTPRoute**, **GRPCRoute**, **TCPRoute**, **TLSRoute**, **UDPRoute**) у `spec.rules[*].backendRefs[*]` **не** додавай поле **`namespace`**, якщо його значення збігається з **`metadata.namespace`** самого маршруту. За замовчуванням Gateway API резолвить backend у тому ж namespace, що й маршрут, тож такий рядок — мертвий: він плутає під час перенесень між середовищами і ламається мовчки, якщо overlay змінює namespace маршруту через Kustomize, а в backendRef залишився старий рядок. Прибери поле — поведінка не зміниться. **`check k8s`** падає на такому збігу.
+
+```yaml
+# ❌ погано — namespace дублює metadata.namespace маршруту
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: admin-site
+  namespace: dev-b2b
+spec:
+  rules:
+    - backendRefs:
+        - name: auth-hl
+          namespace: dev-b2b # ← прибери
+          port: 8080
+```
+
+```yaml
+# ✅ добре — namespace лише в metadata
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: admin-site
+  namespace: dev-b2b
+spec:
+  rules:
+    - backendRefs:
+        - name: auth-hl
+          port: 8080
+```
+
+Якщо backend **дійсно** живе в іншому namespace — поле **`namespace`** у `backendRef` обов'язкове (і потрібен `ReferenceGrant` у тому namespace); правило цього випадку не торкається.
+
 ## ConfigMap: ім'я збігається з Deployment
 
 Якщо в `k8s/base/` є **`configmap.yaml`** і **Deployment**, і цей Deployment посилається рівно на **один** ConfigMap — `metadata.name` ConfigMap має збігатися з `metadata.name` Deployment. Точні умови перевірки — **`check-k8s.mjs`**.
@@ -474,6 +509,28 @@ patches:
           preem: "false"
 ```
 
+### `patches[].target`: лише `kind` і `name`
+
+У `patches[].target` залишай **тільки** **`kind`** і **`name`** — поля **`group`** і **`version`** прибирай. Kustomize резолвить ціль за GVK+name; `group`/`version` — звужувальні фільтри, потрібні лише за реальної колізії `kind+name` між різними API-групами або версіями. У межах одного namespace apiserver зберігає об'єкт у єдиному storage-GVK, тож для звичайних маніфестів така колізія неможлива, і `group`/`version` у `target` — мертвий шум, який ламається мовчки під час змін API (наприклад, перехід `v1beta1` → `v1`).
+
+```yaml
+# ❌ зайві group / version
+patches:
+  - target:
+      group: gateway.networking.k8s.io
+      version: v1beta1
+      kind: Gateway
+      name: gw
+
+# ✅
+patches:
+  - target:
+      kind: Gateway
+      name: gw
+```
+
+**Виняток:** залишай `group` / `version`, лише якщо в дереві overlay реально співіснують ресурси з однаковими `kind`+`name`, але різними API-групами/версіями (наприклад, дві CRD з одним `kind`). У такому разі вкажи мінімальний набір полів, потрібний для дисамбігуації.
+
 ## Перевірка
 
 **`npx @nitra/cursor check k8s`** — програмні критерії в **JSDoc на початку** **`npm/scripts/check-k8s.mjs`**. Якщо під **`k8s`** немає **`*.yaml`** — крок пропущено. Канон **`$schema`** для редактора — розділ **«Визначення схеми YAML`** нижче.

package/mdc/npm-module.mdc

@@ -1,7 +1,7 @@
 ---
 description: Оформлення репозиторію для npm модуля
 alwaysApply: true
-version: '1.8'
+version: '1.9'
 ---
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
@@ -51,11 +51,7 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 ## CHANGELOG
 
-Разом із підвищенням **build**-версії в **`npm/package.json`** оновлюй **`npm/CHANGELOG.md`** — додавай новий запис із номером версії та коротким описом змін у модулі. Без оновлення `CHANGELOG.md` зміни в `npm/` зливати в `main` не можна.
-
-Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/) (новіші версії зверху, мова — українська). Кожен запис починається з рядка `## [версія] - YYYY-MM-DD` і має одну або кілька секцій: `### Added`, `### Changed`, `### Fixed`, `### Removed`.
-
-Файл **`CHANGELOG.md`** має бути в масиві **`files`** у **`npm/package.json`**, щоб публікувався разом із пакетом.
+Окреме правило **`changelog`** ([changelog.mdc](changelog.mdc)) вимагає `npm/CHANGELOG.md` із записом для поточної версії (Keep a Changelog) і присутність `"CHANGELOG.md"` у масиві `files` у `npm/package.json`. Логіка — PR-scoped (сума по гілці vs `dev`).
 
 ## npm publish
 

package/package.json

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

package/scripts/auto-rules.mjs

@@ -26,6 +26,7 @@ export const AUTO_RULE_ORDER = Object.freeze([
   'abie',
   'bun',
   'capacitor',
+  'changelog',
   'docker',
   'ga',
   'graphql',
@@ -54,6 +55,7 @@ export const AUTO_SKILL_ORDER = Object.freeze(['abie-kustomize', 'fix', 'lint'])
  */
 export const AUTO_RULE_DEPENDENCIES = Object.freeze(
   /** @type {Record<string, readonly string[]>} */ ({
+    changelog: Object.freeze(['bun']),
     image: Object.freeze(['vue'])
   })
 )

package/scripts/check-changelog.mjs

@@ -0,0 +1,402 @@
+/**
+ * Перевіряє, що в кожному workspace із незакомічаними/незрелізнутими змінами підвищена `version` у
+ * `<ws>/package.json` і в `<ws>/CHANGELOG.md` присутній запис `## [version] - YYYY-MM-DD`
+ * (формат Keep a Changelog).
+ *
+ * Дві моделі визначення «бази для порівняння» — на рівні воркспейсу:
+ *
+ * 1) **npm-published mode** (`<ws>/package.json` має непорожнє `name`, не `private: true`,
+ *    і має масив `files`): база = опублікована версія в npm-реєстрі (`npm view <name> version`).
+ *    Git не задіяний. Якщо локальна версія відрізняється від опублікованої — потрібен запис
+ *    у CHANGELOG для локальної версії й `"CHANGELOG.md"` у `files`. Якщо `npm view` недосяжний
+ *    (немає мережі / пакет ще не публікувався) — fail-safe pass із поясненням, щоб локальна
+ *    розробка офлайн не блокувалась.
+ *
+ * 2) **local-only mode** (приватні / без `files` воркспейси): PR-scoped перевірка проти `dev`.
+ *    База = `git merge-base <dev> HEAD` (точка розгалуження поточної гілки від `dev`), щоб:
+ *    - на feature-гілці бачити лише унікальні коміти цієї гілки;
+ *    - на `main` після merge `dev → main` diff був порожній (нічого не вимагати);
+ *    - direct-commit на `main` поза PR-flow ловився як зміна, що потребує bump + CHANGELOG.
+ *    Якщо не git-репо, поточна гілка = `dev`, або `dev`/`origin/dev` не існує — пропуск.
+ *
+ * Усі `git` і `npm` виклики — через `execFile`, без shell-інтерполяції.
+ */
+import { execFile } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
+
+const execFileAsync = promisify(execFile)
+
+/** Базова гілка PR — фіксована, без конфіга (див. n-changelog.mdc) */
+const BASE_BRANCH = 'dev'
+
+/** Таймаут на `npm view <name> version` (мс), щоб не блокуватись на офлайні */
+const NPM_VIEW_TIMEOUT_MS = 10_000
+
+/**
+ * Тихо запускає `git` і повертає stdout або `null` при будь-якій помилці.
+ * @param {string[]} args аргументи `git`
+ * @returns {Promise<string | null>}
+ */
+async function gitOrNull(args) {
+  try {
+    const { stdout } = await execFileAsync('git', args)
+    return stdout
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Чи робочий каталог — git-репозиторій.
+ * @returns {Promise<boolean>}
+ */
+async function isInsideGitRepo() {
+  const out = await gitOrNull(['rev-parse', '--is-inside-work-tree'])
+  return typeof out === 'string' && out.trim() === 'true'
+}
+
+/**
+ * Назва поточної гілки (або `HEAD` для detached state).
+ * @returns {Promise<string | null>}
+ */
+async function currentBranchName() {
+  const out = await gitOrNull(['rev-parse', '--abbrev-ref', 'HEAD'])
+  return typeof out === 'string' ? out.trim() : null
+}
+
+/**
+ * Знаходить ref для базової гілки. Перевага локальному `dev`, далі `origin/dev`. Повертає `null`,
+ * якщо жоден не існує.
+ * @returns {Promise<string | null>}
+ */
+async function resolveBaseRef() {
+  for (const ref of [BASE_BRANCH, `origin/${BASE_BRANCH}`]) {
+    const out = await gitOrNull(['rev-parse', '--verify', '--quiet', ref])
+    if (typeof out === 'string' && out.trim().length > 0) {
+      return ref
+    }
+  }
+  return null
+}
+
+/**
+ * Точка розгалуження поточної гілки від `baseRef`. На feature-гілці = коли вона відгалузилась;
+ * на `main` після merge `dev → main` = поточний `dev`. Повертає `null`, якщо merge-base нема.
+ * @param {string} baseRef
+ * @returns {Promise<string | null>}
+ */
+async function resolveMergeBase(baseRef) {
+  const out = await gitOrNull(['merge-base', baseRef, 'HEAD'])
+  if (typeof out !== 'string') return null
+  const sha = out.trim()
+  return sha.length > 0 ? sha : null
+}
+
+/**
+ * Будує pathspec для `git diff` / `ls-files` для воркспейсу.
+ *
+ * Для кореня `.` — це точка плюс magic-виключення кожного підворкспейсу через `:(exclude)<sub>/`,
+ * щоб зміни всередині sub-workspace не вважалися змінами кореня.
+ * Для звичайного воркспейсу — просто `<ws>/`.
+ * @param {string} ws
+ * @param {string[]} subWorkspaces
+ * @returns {string[]}
+ */
+function pathspecForWorkspace(ws, subWorkspaces) {
+  if (ws !== '.') return [`${ws}/`]
+  return ['.', ...subWorkspaces.filter(s => s !== '.').map(s => `:(exclude)${s}/`)]
+}
+
+/**
+ * Чи є зміни (committed або в робочому дереві) у каталозі `<ws>` відносно `baseRef`.
+ *
+ * `git diff --quiet <baseRef> -- <pathspec>` ловить committed-зміни на цій гілці й незбережені
+ * правки tracked-файлів. Untracked-файли — `git ls-files --others --exclude-standard`.
+ * @param {string} baseRef SHA або ref-name (зокрема merge-base)
+ * @param {string} ws
+ * @param {string[]} subWorkspaces
+ * @returns {Promise<boolean>}
+ */
+async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
+  const pathspec = pathspecForWorkspace(ws, subWorkspaces)
+  try {
+    await execFileAsync('git', ['diff', '--quiet', baseRef, '--', ...pathspec])
+  } catch (err) {
+    const code = /** @type {{ code?: number }} */ (err).code
+    if (code === 1) return true
+    return false
+  }
+  const untracked = await gitOrNull(['ls-files', '--others', '--exclude-standard', '--', ...pathspec])
+  return typeof untracked === 'string' && untracked.trim().length > 0
+}
+
+/**
+ * Версія з `<ws>/package.json` на `baseRef` або `null`.
+ * @param {string} baseRef
+ * @param {string} ws
+ * @returns {Promise<string | null>}
+ */
+async function readBaseVersion(baseRef, ws) {
+  const wsPath = ws === '.' ? 'package.json' : `${ws}/package.json`
+  const out = await gitOrNull(['show', `${baseRef}:${wsPath}`])
+  if (out === null) return null
+  try {
+    const parsed = JSON.parse(out)
+    return typeof parsed?.version === 'string' ? parsed.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Чи містить текст `CHANGELOG.md` запис `## [version]` (з опційним `- YYYY-MM-DD`).
+ * @param {string} text
+ * @param {string} version
+ * @returns {boolean}
+ */
+function changelogHasVersionEntry(text, version) {
+  const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
+  const re = new RegExp(String.raw`^##\s+\[${escaped}\]`, 'm')
+  return re.test(text)
+}
+
+/**
+ * Зчитує `<ws>/package.json`. `null`, якщо файл відсутній або JSON некоректний.
+ * @param {string} ws
+ * @returns {Promise<Record<string, unknown> | null>}
+ */
+async function readPackageJsonOrNull(ws) {
+  const path = join(ws, 'package.json')
+  if (!existsSync(path)) return null
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'))
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? /** @type {Record<string, unknown>} */ (parsed)
+      : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Воркспейс публікується в npm: має непорожній `name`, не `private: true`, і має масив `files`.
+ * @param {Record<string, unknown> | null} pkg
+ * @returns {boolean}
+ */
+function isNpmPublishable(pkg) {
+  if (!pkg) return false
+  if (typeof pkg.name !== 'string' || pkg.name.length === 0) return false
+  if (pkg.private === true) return false
+  return Array.isArray(pkg.files)
+}
+
+/**
+ * Опублікована версія пакета в npm-реєстрі. `null` — пакет не знайдено / нема мережі / помилка.
+ * Дефолтна імплементація — `npm view <name> version` із таймаутом, щоб не блокуватись офлайн.
+ * @param {string} name
+ * @returns {Promise<string | null>}
+ */
+async function defaultGetPublishedVersion(name) {
+  try {
+    const { stdout } = await execFileAsync('npm', ['view', name, 'version'], { timeout: NPM_VIEW_TIMEOUT_MS })
+    const v = stdout.trim()
+    return v.length > 0 ? v : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Перевіряє масив `files` у `<ws>/package.json`: якщо оголошено — має містити `"CHANGELOG.md"`.
+ * @param {Record<string, unknown> | null} pkg
+ * @param {string} ws
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ */
+function checkFilesArrayContainsChangelog(pkg, ws, pass, fail) {
+  if (!pkg || !Array.isArray(pkg.files)) return
+  const pkgPath = join(ws, 'package.json')
+  if (pkg.files.includes('CHANGELOG.md')) {
+    pass(`${pkgPath}: files містить "CHANGELOG.md"`)
+  } else {
+    fail(`${pkgPath}: масив files має містити "CHANGELOG.md", щоб публікувати changelog із пакетом`)
+  }
+}
+
+/**
+ * Перевіряє наявність запису у `<ws>/CHANGELOG.md` для версії `version`.
+ * @param {string} ws
+ * @param {string} version
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ * @returns {Promise<boolean>} `false`, якщо файл відсутній або немає запису
+ */
+async function verifyChangelogEntry(ws, version, pass, fail) {
+  const label = ws === '.' ? '<root>' : ws
+  const changelogPath = join(ws, 'CHANGELOG.md')
+  if (!existsSync(changelogPath)) {
+    fail(`${label}: відсутній ${changelogPath} (Keep a Changelog, див. n-changelog.mdc)`)
+    return false
+  }
+  const text = await readFile(changelogPath, 'utf8')
+  if (changelogHasVersionEntry(text, version)) {
+    pass(`${changelogPath}: знайдено запис для версії ${version}`)
+    return true
+  }
+  fail(`${changelogPath}: відсутній запис для ${version} (формат "## [${version}] - YYYY-MM-DD")`)
+  return false
+}
+
+/**
+ * npm-published режим: порівнює локальну `version` з опублікованою в реєстрі. Якщо вони
+ * відрізняються — вимагає запис у CHANGELOG і `"CHANGELOG.md"` у `files`. Якщо реєстр недосяжний,
+ * правило fail-safe пасує (щоб офлайн-розробка не блокувалась).
+ * @param {string} ws
+ * @param {Record<string, unknown>} pkg
+ * @param {(name: string) => Promise<string | null>} getPublishedVersion
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ */
+async function checkPublishedWorkspace(ws, pkg, getPublishedVersion, pass, fail) {
+  const label = ws === '.' ? '<root>' : ws
+  const Vcurrent = typeof pkg.version === 'string' ? pkg.version : null
+  if (!Vcurrent) {
+    fail(`${label}: у package.json відсутнє поле version (npm-published воркспейс)`)
+    return
+  }
+  const name = /** @type {string} */ (pkg.name)
+  const Vpublished = await getPublishedVersion(name)
+  if (Vpublished === null) {
+    pass(`${label}: ${name} — опублікована версія недоступна (мережа/реєстр), перевірку пропущено`)
+    return
+  }
+  if (Vpublished === Vcurrent) {
+    pass(`${label}: ${name}@${Vcurrent} вже опубліковано — змін до релізу немає`)
+    return
+  }
+  pass(`${label}: ${name} — нова локальна версія (${Vpublished} → ${Vcurrent})`)
+  await verifyChangelogEntry(ws, Vcurrent, pass, fail)
+  checkFilesArrayContainsChangelog(pkg, ws, pass, fail)
+}
+
+/**
+ * local-only режим: PR-scoped перевірка проти `dev` через `git merge-base`. Викликається лише
+ * для воркспейсів, де є реальні зміни щодо merge-base.
+ * @param {string} mergeBase SHA точки розгалуження
+ * @param {string} ws
+ * @param {Record<string, unknown> | null} pkg
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ */
+async function checkLocalOnlyChangedWorkspace(mergeBase, ws, pkg, pass, fail) {
+  const label = ws === '.' ? '<root>' : ws
+  const Vcurrent = typeof pkg?.version === 'string' ? pkg.version : null
+  if (!Vcurrent) {
+    fail(`${label}: у package.json відсутнє поле version (потрібне для запису в CHANGELOG)`)
+    return
+  }
+  const Vbase = await readBaseVersion(mergeBase, ws)
+  if (Vbase !== null && Vbase === Vcurrent) {
+    fail(
+      `${label}: у цій гілці є зміни, але version у ${join(ws, 'package.json')} не підвищено (на ${BASE_BRANCH} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові на PR`
+    )
+    return
+  }
+  pass(`${label}: version підвищено (${Vbase ?? '∅'} → ${Vcurrent})`)
+  if (!(await verifyChangelogEntry(ws, Vcurrent, pass, fail))) return
+  checkFilesArrayContainsChangelog(pkg, ws, pass, fail)
+}
+
+/**
+ * Виконує local-only перевірку для всіх workspace-ів, у яких немає npm-published режиму.
+ * @param {string[]} localOnlyWorkspaces
+ * @param {Map<string, Record<string, unknown> | null>} pkgByWs
+ * @param {string[]} subWorkspaces
+ * @param {(msg: string) => void} pass
+ * @param {(msg: string) => void} fail
+ * @returns {Promise<void>}
+ */
+async function runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, pass, fail) {
+  if (localOnlyWorkspaces.length === 0) return
+
+  if (!(await isInsideGitRepo())) {
+    pass('changelog: не git-репозиторій — local-only перевірку пропущено')
+    return
+  }
+  const branch = await currentBranchName()
+  if (branch === BASE_BRANCH) {
+    pass(`changelog: поточна гілка = ${BASE_BRANCH} — local-only перевірку пропущено`)
+    return
+  }
+  const baseRef = await resolveBaseRef()
+  if (!baseRef) {
+    pass(`changelog: ref ${BASE_BRANCH} (та origin/${BASE_BRANCH}) не знайдено — local-only перевірку пропущено`)
+    return
+  }
+  const mergeBase = await resolveMergeBase(baseRef)
+  if (!mergeBase) {
+    pass(`changelog: merge-base з ${baseRef} не знайдено — local-only перевірку пропущено`)
+    return
+  }
+
+  let checkedAny = false
+  for (const ws of localOnlyWorkspaces) {
+    if (!(await workspaceHasChangesAgainstBase(mergeBase, ws, subWorkspaces))) continue
+    checkedAny = true
+    await checkLocalOnlyChangedWorkspace(mergeBase, ws, pkgByWs.get(ws) ?? null, pass, fail)
+  }
+  if (!checkedAny) {
+    pass(`changelog: local-only воркспейси без змін відносно merge-base(${baseRef})`)
+  }
+}
+
+/**
+ * Перевіряє відповідність проєкту правилу changelog.mdc.
+ * @param {object} [opts]
+ * @param {(name: string) => Promise<string | null>} [opts.getPublishedVersion] перевизначення для тестів
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check(opts = {}) {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+  const getPublishedVersion = opts.getPublishedVersion ?? defaultGetPublishedVersion
+
+  const workspaces = await getMonorepoPackageRootDirs(process.cwd())
+  const subWorkspaces = workspaces.filter(w => w !== '.')
+
+  /** @type {Map<string, Record<string, unknown> | null>} */
+  const pkgByWs = new Map()
+  /** @type {string[]} */
+  const publishedWorkspaces = []
+  /** @type {string[]} */
+  const localOnlyWorkspaces = []
+  for (const ws of workspaces) {
+    const pkg = await readPackageJsonOrNull(ws)
+    pkgByWs.set(ws, pkg)
+    if (isNpmPublishable(pkg)) {
+      publishedWorkspaces.push(ws)
+    } else {
+      localOnlyWorkspaces.push(ws)
+    }
+  }
+
+  for (const ws of publishedWorkspaces) {
+    await checkPublishedWorkspace(
+      ws,
+      /** @type {Record<string, unknown>} */ (pkgByWs.get(ws)),
+      getPublishedVersion,
+      pass,
+      fail
+    )
+  }
+
+  await runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, pass, fail)
+
+  return reporter.getExitCode()
+}

package/scripts/check-k8s.mjs

@@ -38,6 +38,8 @@
  * кожен **Service** — **`spec.clusterIP: None`** та ім’я на **`-hl`**. У маршрутах **Gateway API**
  * (**`HTTPRoute`**, **`GRPCRoute`**, **`TCPRoute`**, **`TLSRoute`**, **`UDPRoute`**, група **`gateway.networking.k8s.io`**)
  * посилання **`backendRefs` / `backendRef`** на **Service** мають вказувати лише сервіси з суфіксом **`-hl`** у **`name`**.
+ * Поле **`namespace`** у **`backendRef`**, що збігається з **`metadata.namespace`** самого маршруту, — надлишкове:
+ * прибери його, бо за замовчуванням Gateway API резолвить backend у тому ж namespace, що й маршрут (див. k8s.mdc).
  * **HealthCheckPolicy** (**`networking.gke.io/v1`**, GKE): **`spec.targetRef`** на **Service** — **`name`** з суфіксом **`-hl`** (див. k8s.mdc).
  * Якщо **`kustomization.yaml`** посилається на **`svc.yaml`** (**`resources`**, **`bases`**, **`components`**, **`crds`**,
  * **`patches[].path`**, **`patchesStrategicMerge`**), у **тому ж** файлі має бути посилання на відповідний **`svc-hl.yaml`**
@@ -55,6 +57,11 @@
  * Для **`patchesStrategicMerge`** і для **`patches[].path`** без **`target`** і без inline **`patch`** (зовнішній strategic-merge)
  * кожен YAML-документ з кореневим **`kind`** і **`metadata.name`** також звіряється з цим каталогом.
  *
+ * **Зайві `group` / `version` у `patches[].target` / `patchesJson6902[].target`:** якщо в інвентарі **`resources`** /
+ * **`bases`** / **`components`** / **`crds`** (рекурсивно) за **`kind`** + **`name`** немає колізії між різними
+ * API-групами/версіями, поля **`group`** і **`version`** у **`target`** треба прибрати — Kustomize резолвить ціль
+ * за **GVK + name**, а зайві поля ламаються мовчки під час змін API (k8s.mdc «patches[].target: лише kind і name»).
+ *
  * Явні винятки до загальної логіки yannh/datree — таблиця **`EXPLICIT_K8S_SCHEMAS`** (`Map`): ключ
  * **`apiVersion`, `kind`, `type`** (для CRD без поля `type` у маніфесті — зірочка **`*`** як третій
  * компонент). Спочатку шукається збіг за фактичним `type`, потім за **`*`**.
@@ -1323,6 +1330,52 @@ function failIfExplicitPatchTargetsNotInCatalog(rel, first, catalog, fail) {
   }
 }
 
+/**
+ * Зайві **`group`** / **`version`** у **`patches[].target`** / **`patchesJson6902[].target`**: якщо в інвентарі за **`kind`** + **`name`** немає колізії між різними API-групами/версіями, ці поля треба прибрати (k8s.mdc «patches[].target: лише kind і name»).
+ * @param {string} rel відносний шлях до kustomization.yaml
+ * @param {Record<string, unknown>} first корінь Kustomization
+ * @param {KustomizeResourceDescriptor[]} catalog інвентар resources/bases/…
+ * @param {(msg: string) => void} fail реєстрація помилки
+ * @returns {void}
+ */
+function failIfExplicitPatchTargetsHaveRedundantGroupVersion(rel, first, catalog, fail) {
+  for (const { section, index, target } of extractExplicitPatchTargetsFromKustomization(first)) {
+    if (target === null || typeof target !== 'object' || Array.isArray(target)) {
+      continue
+    }
+    const t = /** @type {Record<string, unknown>} */ (target)
+    const kind = typeof t.kind === 'string' ? t.kind.trim() : ''
+    const name = typeof t.name === 'string' ? t.name.trim() : ''
+    if (kind === '' || name === '') {
+      continue
+    }
+    if (patchTargetUsesSelector(t)) {
+      continue
+    }
+    const tgtGroup = typeof t.group === 'string' ? t.group.trim() : ''
+    const tgtVersion = typeof t.version === 'string' ? t.version.trim() : ''
+    if (tgtGroup === '' && tgtVersion === '') {
+      continue
+    }
+    const matchingByKindName = catalog.filter(r => r.kind === kind && r.name === name)
+    const distinctGvk = new Set(matchingByKindName.map(r => `${r.group}/${r.version}`))
+    if (distinctGvk.size > 1) {
+      continue
+    }
+    /** @type {string[]} */
+    const redundant = []
+    if (tgtGroup !== '') {
+      redundant.push('group')
+    }
+    if (tgtVersion !== '') {
+      redundant.push('version')
+    }
+    fail(
+      `${rel}: ${section}[${index}].target — прибери зайві поля ${redundant.join(', ')}; для kind=${kind}, name=${name} в інвентарі немає колізії між різними API-групами/версіями (див. k8s.mdc «patches[].target: лише kind і name»)`
+    )
+  }
+}
+
 /**
  * Документи з YAML-файлу мають мати дескриптор у **catalog** (інвентар resources).
  * @param {string} rel відносний шлях до kustomization.yaml
@@ -1525,6 +1578,7 @@ async function validatePatchTargetsOneKustomizationFile(root, kustAbs, rootNorm,
   const kustDir = dirname(resolve(kustAbs))
   const kustNs = typeof rec.namespace === 'string' && rec.namespace.trim() !== '' ? rec.namespace.trim() : ''
   failIfExplicitPatchTargetsNotInCatalog(rel, first, catalog, fail)
+  failIfExplicitPatchTargetsHaveRedundantGroupVersion(rel, first, catalog, fail)
   await failIfPathOnlyPatchesNotInCatalog(rel, rec.patches, kustDir, rootNorm, root, catalog, kustNs, fail)
   await failIfStrategicMergePatchesNotInCatalog(
     rel,
@@ -2880,7 +2934,49 @@ export function collectGatewayApiRouteBackendServiceNames(spec) {
 }
 
 /**
- * Один документ: маршрут Gateway API має посилатися на **Service** з суфіксом **`-hl`**.
+ * Збирає **`backendRef`** до **Service** з полем **`namespace`**, що збігається з namespace маршруту.
+ *
+ * Поле **`namespace`** у такому **`backendRef`** надлишкове: за замовчуванням Gateway API резолвить backend
+ * у тому ж namespace, що й сам маршрут (див. k8s.mdc). Зайві поля у YAML — джерело розсинхрону між середовищами.
+ * @param {unknown} spec значення **`spec`** маршруту
+ * @param {string} routeNs **`metadata.namespace`** маршруту (непорожній рядок)
+ * @returns {string[]} імена backend-сервісів з надлишковим **`namespace`** (можливі дублікати)
+ */
+export function collectGatewayApiRouteBackendRefsWithRedundantNamespace(spec, routeNs) {
+  /** @type {string[]} */
+  const out = []
+
+  /**
+   * @param {unknown} node вузол для обходу
+   * @returns {void}
+   */
+  function walk(node) {
+    if (node === null || node === undefined) return
+    if (Array.isArray(node)) {
+      for (const x of node) {
+        walk(x)
+      }
+      return
+    }
+    if (typeof node !== 'object') return
+    if (isGatewayApiBackendRefToService(node)) {
+      const o = /** @type {Record<string, unknown>} */ (node)
+      if (typeof o.namespace === 'string' && o.namespace === routeNs) {
+        out.push(String(o.name))
+      }
+    }
+    for (const v of Object.values(node)) {
+      walk(v)
+    }
+  }
+
+  walk(spec)
+  return out
+}
+
+/**
+ * Один документ: маршрут Gateway API має посилатися на **Service** з суфіксом **`-hl`**;
+ * у **`backendRef`** не має дублюватися **`namespace`**, що збігається з **`metadata.namespace`** маршруту.
  * @param {string} rel відносний шлях до файлу
  * @param {number} docIndex 1-based індекс документа
  * @param {Record<string, unknown>} rec корінь маніфесту
@@ -2906,6 +3002,18 @@ function failIfGatewayRouteUsesNonHeadlessService(rel, docIndex, rec, fail) {
       )
     }
   }
+  const meta = rec.metadata
+  if (meta !== null && typeof meta === 'object' && !Array.isArray(meta)) {
+    const routeNs = /** @type {Record<string, unknown>} */ (meta).namespace
+    if (typeof routeNs === 'string' && routeNs !== '') {
+      const redundant = collectGatewayApiRouteBackendRefsWithRedundantNamespace(rec.spec, routeNs)
+      for (const svcName of redundant) {
+        fail(
+          `${rel}: Gateway API ${kind} (документ ${docIndex}): backendRef «${svcName}» має namespace «${routeNs}», що збігається з metadata.namespace маршруту — прибери поле namespace з backendRef (див. k8s.mdc)`
+        )
+      }
+    }
+  }
 }
 
 /**

package/scripts/check-npm-module.mjs

@@ -9,9 +9,6 @@
  * Якщо таких файлів немає — layout через `npm/tsconfig.emit-types.json`: поле `types` має вказувати на існуючий
  * файл під `./types/…`, у hk — `tsc -p tsconfig.emit-types.json`, у JSON-конфігу — потрібні compilerOptions для emit.
  *
- * Окремо перевіряється `npm/CHANGELOG.md`: файл існує, є в `files` у `npm/package.json` і містить запис
- * для поточної версії (формат `## [X.Y.Z] - YYYY-MM-DD`, Keep a Changelog).
- *
  * Поля workflow перевіряються після **YAML parse**, щоб не плутати з коментарями.
  */
 import { existsSync } from 'node:fs'
@@ -37,9 +34,6 @@ const TYPES_INDEX = './types/index.d.ts'
 /** Файл проєкту TypeScript для emit без каталогу `src` (див. npm-module.mdc) */
 const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
 
-/** Шлях до `CHANGELOG.md` в каталозі npm-модуля */
-const CHANGELOG_PATH = 'npm/CHANGELOG.md'
-
 /**
  * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
  * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
@@ -205,53 +199,6 @@ async function checkNpmPackageJson(useSrcJsLayout, passFn, failFn) {
   }
 }
 
-/**
- * Чи містить текст `CHANGELOG.md` запис заголовка для конкретної версії
- * у форматі Keep a Changelog: `## [X.Y.Z]` (з опційним `- YYYY-MM-DD`).
- * @param {string} text вміст `CHANGELOG.md`
- * @param {string} version номер версії з `npm/package.json`
- * @returns {boolean} `true`, якщо знайдено заголовок версії
- */
-function changelogHasVersionEntry(text, version) {
-  const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
-  const re = new RegExp(String.raw`^##\s+\[${escaped}\]`, 'm')
-  return re.test(text)
-}
-
-/**
- * Перевіряє наявність і вміст `npm/CHANGELOG.md`, а також що він є в `files` у `npm/package.json`.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- */
-async function checkChangelog(passFn, failFn) {
-  if (!existsSync(CHANGELOG_PATH)) {
-    failFn(`Відсутній ${CHANGELOG_PATH} (npm-module.mdc: CHANGELOG)`)
-    return
-  }
-  passFn(`${CHANGELOG_PATH} існує`)
-
-  if (existsSync('npm/package.json')) {
-    const npmPkg = JSON.parse(await readFile('npm/package.json', 'utf8'))
-    if (Array.isArray(npmPkg.files) && npmPkg.files.includes('CHANGELOG.md')) {
-      passFn('npm/package.json: files містить "CHANGELOG.md"')
-    } else {
-      failFn('npm/package.json: масив files має містити "CHANGELOG.md"')
-    }
-
-    const version = typeof npmPkg.version === 'string' ? npmPkg.version : null
-    if (version) {
-      const text = await readFile(CHANGELOG_PATH, 'utf8')
-      if (changelogHasVersionEntry(text, version)) {
-        passFn(`${CHANGELOG_PATH}: знайдено запис для версії ${version}`)
-      } else {
-        failFn(
-          `${CHANGELOG_PATH}: відсутній запис для поточної версії ${version} (формат Keep a Changelog: "## [${version}] - YYYY-MM-DD")`
-        )
-      }
-    }
-  }
-}
-
 /**
  * Перевіряє npm/tsconfig.emit-types.json.
  * @param {(msg: string) => void} passFn callback при успішній перевірці
@@ -397,8 +344,6 @@ export async function check() {
 
   await checkNpmPackageJson(useSrcJsLayout, pass, fail)
 
-  await checkChangelog(pass, fail)
-
   if (!useSrcJsLayout) {
     await checkEmitTypesConfig(pass, fail)
   }