@nitra/cursor 1.8.58 → 1.8.63

package/README.md

@@ -39,7 +39,7 @@
 
 - **Структура Kustomize:** спільне виноситься в **`base`**; вміст **base** відповідає тому, як має виглядати середовище **dev**; окремої директорії **`dev/`** немає — за dev відповідає **`base`**. У інших середовищах — тонкі **overlays** (часто лише **`kustomization.yaml`** і patches / оверрайди).
 - **Namespace** задається в **`kustomization.yaml`** (`namespace:`), а не через **`metadata.namespace`** у кожному ресурсі; окремі patches лише на зміну **namespace** не потрібні.
-- У **Deployment** для кожного контейнера: **`resources`**, **`imagePullPolicy: Always`** (перевіряє **`npx @nitra/cursor check k8s`**).
+- У **Deployment** для кожного контейнера: **`resources`** (перевіряє **`npx @nitra/cursor check k8s`**);
 - Рядки в **base**, які змінюються в overlays, позначайте коментарем на рядку (узгоджено в команді), наприклад: `# буде замінено через kustomize`.
 - Після перенесення в **`base`** / overlays **видаляйте** застарілі маніфести та каталоги, які більше не потрібні.
 

package/mdc/k8s.mdc

@@ -1,6 +1,6 @@
 ---
 description: K8s YAML — $schema (yaml-language-server); lint-k8s (kubeconform, kubescape); check-k8s
-version: '1.23'
+version: '1.24'
 globs: "**/k8s/**/*.yaml"
 alwaysApply: false
 ---
@@ -104,7 +104,7 @@ resources: {}
 
 Так маніфест явно резервує місце під **`requests` / `limits`** і уникає випадкового пропуску секції. **`check k8s`** перевіряє це для кожного YAML-документа **`Deployment`** у файлах під **`k8s`**.
 
-У кожному контейнері **`Deployment`** має бути **`imagePullPolicy: Always`** (див. **`check k8s`**).
+**`imagePullPolicy`:** у маніфестах не вимагається; Kubernetes за замовчуванням: образ **без тега** або з **`:latest`** → **Always**, з іншим тегом → **IfNotPresent**. **`check k8s`** це поле не перевіряє.
 
 Якщо в **`Deployment`** у **`spec.template.spec.containers`** або **`initContainers`** задано образ **`hasura/graphql-engine`**, у полі **`image`** має бути саме **`hasura/graphql-engine:v2.48.15.ubi.amd64`** (для еквівалента Docker Hub допускається префікс **`docker.io/`**). Інші теги або сторонні реєстри з тим самим репозиторієм **`hasura/graphql-engine`** — порушення **`check k8s`**.
 
@@ -117,6 +117,14 @@ resources: {}
 
 Вони потрібні для інтеграції з **Ingress** / класичним балансуванням GKE; після переходу на **Gateway API** їх слід **прибрати** з маніфестів. **`check k8s`** завершиться помилкою, якщо хоча б один із цих ключів присутній.
 
+## Service: `svc.yaml` і `svc-hl.yaml` (Gateway API)
+
+- У тому самому каталозі, де лежить **`svc.yaml`**, обов’язково має бути **`svc-hl.yaml`**. Якщо файлу ще немає — створи його як копію **`svc.yaml`**: для кожного **Service** задай **`metadata.name`** з суфіксом **`-hl`**, **`spec.clusterIP: None`** (headless), збережи селектор і порти як у кластерного сервісу; **`check k8s`** не генерує файли автоматично.
+- У **`svc.yaml`** кожен **Service** має мати **`spec.type: ClusterIP`**.
+- У **`svc-hl.yaml`** кожен **Service** має мати **`spec.clusterIP: None`** та **`metadata.name`**, що закінчується на **`-hl`**, узгоджено з відповідним ім’ям у **`svc.yaml`** (наприклад **`app`** → **`app-hl`**).
+- У маршрутах **Gateway API** з групи **`gateway.networking.k8s.io`** (**`HTTPRoute`**, **`GRPCRoute`**, **`TCPRoute`**, **`TLSRoute`**, **`UDPRoute`**) посилання **`backendRefs`** / **`backendRef`** на **Service** мають вказувати лише сервіси з цього headless-файлу (ім’я з суфіксом **`-hl`**).
+- Якщо **`svc.yaml`** підключено через **`kustomization.yaml`** (**`resources`**, **`bases`**, **`components`**, **`crds`**, **`patches[].path`**, **`patchesStrategicMerge`**), у **тому ж** **`kustomization.yaml`** додай посилання на відповідний **`svc-hl.yaml`** (той самий відносний префікс каталогу, що й для **`svc.yaml`**).
+
 ## Kustomize: структура каталогів (`base` / overlays)
 
 Трансформуй дерева **`**/k8s`**, щоб **винести спільне** через [Kustomize](https://kustomize.io/): один канонічний **`base`** і тонкі **overlays** для інших середовищ.
@@ -176,27 +184,23 @@ resources: {}
 
 ## Перевірка
 
-**`npx @nitra/cursor check k8s`** — критерії збігаються з розділом **«Що закодовано в `check-k8s.mjs`»** і з **«Визначення схеми YAML»** вище. Якщо під `k8s` немає `*.yaml` — перевірку пропущено. Інший зміст маніфесту — вручну / **`lint-k8s`**.
+**`npx @nitra/cursor check k8s`** — деталі умов у **JSDoc на початку** **`npm/scripts/check-k8s.mjs`**; канон URL **`$schema`** для редактору — розділ **«Визначення схеми YAML»** нижче. Якщо під `k8s` немає `*.yaml` — перевірку пропущено. Решту політик кластера / compliance закриває **`lint-k8s`**.
 
 Після змін у маніфестах: **`bun run lint-k8s`** (kubeconform + kubescape).
 
 ## Що закодовано в `check-k8s.mjs`
 
-При зміні правил синхронно оновлюй **`YANNH_PIN`**, **`YANNH_REF`** (якщо зміниться гілка за замовчуванням у репо yannh), **`YANNH_GROUPS`**, **`DATREE_CRD_BASE`** (GitHub Pages каталогу CRD), а в **`run-k8s.mjs`** — константу **`KUBERNETES_VERSION`** і **`DATREE_CRD_SCHEMA_LOCATION`** (узгоджено з базою datree у цьому правилі).
+Не дублюй тут повний перелік — він у **верхньому JSDoc** **`npm/scripts/check-k8s.mjs`** і в константах (**`YANNH_PIN`**, **`YANNH_GROUPS`**, **`EXPLICIT_K8S_SCHEMAS`**, **`CLUSTER_SCOPED_KINDS`**, **`HASURA_GRAPHQL_ENGINE_IMAGE`** тощо).
+
+Коротко: **`$schema`** (один modeline, без **`.yml`** під **`k8s`**), заборона **Ingress**, **Deployment.resources**, пін **hasura/graphql-engine**, **Service** без анотацій NEG/backend-config, пари **`svc.yaml`** / **`svc-hl.yaml`** (**ClusterIP** / headless **`-hl`**) і їхні записи в **`kustomization.yaml`**, **Gateway API** маршрути — **backendRef** лише на **`-hl`**, **`metadata.namespace`** залежно від **base** і графа Kustomize, заборона **`…/k8s/dev/…`**, непорожній **`namespace:`** у **`k8s/base/kustomization.yaml`**, видалення файлів, де всі документи — лише **BackendConfig** (змішані файли — помилка).
 
-- Обхід з пропуском `node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`.
-- **`file:`** у `$schema` — URL до apiVersion/kind не звіряється; **`https:`** — kustomization за іменем файлу → Schema Store; далі перевіряється **`EXPLICIT_K8S_SCHEMAS`** (`Map`: `apiVersion` + `kind` + `type`, для записів без `type` у маніфесті — третій компонент **`*`**); потім `v1` → yannh; група з `YANNH_GROUPS` → yannh; інакше → datree (GitHub Pages), крім рядків явної таблиці (наприклад **InfisicalSecret** — raw на `main`).
-- У кожному YAML-документі з **`kind: Deployment`** — парсинг через **`yaml`**: у кожного елемента **`spec.template.spec.containers[]`** має існувати ключ **`resources`** зі значенням-об'єктом (допускається порожній **`{}`**); у кожного контейнера — **`imagePullPolicy: Always`**.
-- **Namespace у маніфестах (не ім’я `kustomization`):** ресурсні YAML у **`…/k8s/base/`** — **завжди** непорожній **`metadata.namespace`**. Інакше будується множина шляхів, досяжних з **`kustomization.yaml`** через **`resources`**, **`bases`**, **`components`**, **`crds`**, **`patches[].path`**, **`patchesStrategicMerge`**, з рекурсією в каталоги з дочірнім **`kustomization.yaml`**: для таких файлів **поза** **`k8s/base`** — **заборона** **`metadata.namespace`**; для файлів поза **`k8s/base`** і поза множиною — **вимога** непорожнього **`metadata.namespace`** (крім **`CLUSTER_SCOPED_KINDS`**).
-- Документи з **`kind: Ingress`** — заборонені (потрібен перехід на Gateway API, див. розділ **Ingress → Gateway API**).
-- Заборона шляхів **`…/k8s/dev/…`** (окремої директорії **`dev`** під **`k8s`** не має бути).
-- Якщо в дереві є **`k8s/base/kustomization.yaml`**, у першому документі **завжди** має бути непорожнє поле **`namespace`** (типово **`dev`**; див. розділ **Namespace**).
+При зміні **PIN** версії Kubernetes оновлюй узгоджено **`check-k8s.mjs`**, **`run-k8s.mjs`** (**`KUBERNETES_VERSION`**, **`DATREE_CRD_SCHEMA_LOCATION`**) і розділи **lint-k8s** / **Визначення схеми YAML** у цьому файлі (**`YANNH_REF`**, **`YANNH_GROUPS`**, **`DATREE_CRD_BASE`** — за потреби в скрипті).
 
 ## Коли застосовувати (агентам)
 
 - Зміни в k8s YAML — після правок **`check k8s`**.
 - Якщо перший рядок уже коректний і URL відповідає `apiVersion` / `kind` — не дублюй; змінився ресурс — онови лише `$schema`.
-- У **`Deployment`** без поля **`resources`** у контейнері — додай **`resources: {}`** (див. розділ **Deployment: `resources`**); додай **`imagePullPolicy: Always`** для кожного контейнера.
+- У **`Deployment`** без поля **`resources`** у контейнері — додай **`resources: {}`** (див. розділ **Deployment: `resources`**). **`imagePullPolicy`** за потреби не дублюй — достатньо політики Kubernetes за тегом образу.
 - Дотримуйся структури **Kustomize** (`base` = dev, overlays без дублювання `base`, коментарі для рядків, що змінюються в overlay). У **`base/kustomization.yaml`** завжди задавай непорожній **`namespace:`**. У **`k8s/base`** у кожному ресурсному YAML має бути явний **`metadata.namespace`**. Поза **base**, якщо не хочеш **`metadata.namespace`** у файлі — підключи його до kustomization (**`resources`** / **`patches`** тощо); інакше додай явний **`metadata.namespace`**.
 - Після міграції на нову структуру **видали** застарілі файли та каталоги, які вже замінені (див. **Міграція зі старої структури**).
 

package/package.json

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

package/scripts/check-k8s.mjs

@@ -7,8 +7,10 @@
  *
  * Додатково: у кожному YAML-документі з **`kind: Deployment`** у кожного контейнера
  * **`spec.template.spec.containers[]`** має бути ключ **`resources`** (значення — об'єкт, допускається
- * порожній **`{}`**) та **`imagePullPolicy: Always`**. Якщо серед **`containers`** / **`initContainers`**
- * є образ **`hasura/graphql-engine`**, дозволено лише пін **`HASURA_GRAPHQL_ENGINE_IMAGE`** (див. k8s.mdc).
+ * порожній **`{}`**). Поле **`imagePullPolicy`** не перевіряється — діють типові правила Kubernetes
+ * (`:latest` або без тега → **Always**, інші теги → **IfNotPresent**). Якщо серед **`containers`** /
+ * **`initContainers`** є образ **`hasura/graphql-engine`**, дозволено лише пін **`HASURA_GRAPHQL_ENGINE_IMAGE`**
+ * (див. k8s.mdc).
  *
  * **Namespace і Kustomize:** YAML у **`…/k8s/base/`** (окрім імені **`kustomization.yaml`**)
  * завжди має **непорожній** **`metadata.namespace`** у відповідних документах (узгоджено з dev у репозиторії),
@@ -19,9 +21,22 @@
  *
  * **`kind: Ingress`** заборонено (потрібен перехід на Gateway API).
  *
+ * Файли під **`k8s`**, де всі YAML-документи — лише **`kind: BackendConfig`**, **видаляються** автоматично.
+ * Якщо **BackendConfig** змішано з іншими ресурсами в одному файлі — перевірка завершується помилкою (розділи маніфести).
+ *
  * У **`kind: Service`** у **`metadata.annotations`** не повинно бути ключів **`cloud.google.com/neg`**
  * та **`cloud.google.com/backend-config`** (див. k8s.mdc).
  *
+ * Файли **`svc.yaml`** / **`svc-hl.yaml`** у **одному каталозі** (див. k8s.mdc): для кожного **`svc.yaml`**
+ * поруч обов’язковий **`svc-hl.yaml`** (headless-копія: той самий селектор/порти, **`metadata.name`** з суфіксом **`-hl`**,
+ * **`spec.clusterIP: None`**). У **`svc.yaml`** кожен **Service** має **`spec.type: ClusterIP`**. У **`svc-hl.yaml`**
+ * кожен **Service** — **`spec.clusterIP: None`** та ім’я на **`-hl`**. У маршрутах **Gateway API**
+ * (**`HTTPRoute`**, **`GRPCRoute`**, **`TCPRoute`**, **`TLSRoute`**, **`UDPRoute`**, група **`gateway.networking.k8s.io`**)
+ * посилання **`backendRefs` / `backendRef`** на **Service** мають вказувати лише сервіси з суфіксом **`-hl`** у **`name`**.
+ * Якщо **`kustomization.yaml`** посилається на **`svc.yaml`** (**`resources`**, **`bases`**, **`components`**, **`crds`**,
+ * **`patches[].path`**, **`patchesStrategicMerge`**), у **тому ж** файлі має бути посилання на відповідний **`svc-hl.yaml`**
+ * в **тому ж каталозі**, що й **`svc.yaml`** (логіка збігається з **`pathsFromKustomizationObject`**).
+ *
  * Структура **Kustomize** (див. k8s.mdc): заборона шляхів **`…/k8s/dev/…`**; у **`k8s/base/kustomization.yaml`**
  * завжди має бути непорожнє поле **`namespace:`** (перевірка, якщо файл існує).
  *
@@ -31,7 +46,7 @@
  * Dockerfile — правило docker.mdc, скрипт check-docker.mjs.
  */
 import { existsSync } from 'node:fs'
-import { readFile, stat } from 'node:fs/promises'
+import { readFile, stat, unlink } from 'node:fs/promises'
 import { basename, dirname, join, relative, resolve } from 'node:path'
 
 import { parseAllDocuments } from 'yaml'
@@ -291,6 +306,79 @@ function pathsFromKustomizationObject(obj) {
   return out
 }
 
+/**
+ * Чи для кожного посилання kustomization на файл **`svc.yaml`** у списку є посилання на sibling **`svc-hl.yaml`**
+ * (той самий каталог після **`resolve`** відносно каталогу **`kustomization.yaml`**).
+ * @param {string} kustomizationDir абсолютний шлях до каталогу з **`kustomization.yaml`**
+ * @param {string[]} pathRefs рядки з **`pathsFromKustomizationObject`**
+ * @returns {string | null} текст порушення або null, якщо ок
+ */
+export function kustomizationSvcYamlMissingSvcHlViolation(kustomizationDir, pathRefs) {
+  /** @type {Set<string>} */
+  const resolved = new Set()
+  for (const ref of pathRefs) {
+    if (typeof ref === 'string' && !ref.includes('://')) {
+      resolved.add(resolve(kustomizationDir, ref))
+    }
+  }
+  for (const ref of pathRefs) {
+    if (typeof ref === 'string' && !ref.includes('://')) {
+      const abs = resolve(kustomizationDir, ref)
+      if (basename(abs).toLowerCase() === 'svc.yaml') {
+        const hlAbs = resolve(dirname(abs), 'svc-hl.yaml')
+        if (!resolved.has(hlAbs)) {
+          return `kustomization посилається на «${ref}» — додай у тому ж kustomization.yaml посилання на відповідний svc-hl.yaml (очікуваний шлях поруч, напр. той самий префікс каталогу + svc-hl.yaml; див. k8s.mdc)`
+        }
+      }
+    }
+  }
+  return null
+}
+
+/**
+ * Перевіряє всі **`kustomization.yaml`** під **`k8s`**: разом із **`svc.yaml`** має бути **`svc-hl.yaml`** у полях шляхів.
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlFiles абсолютні шляхи до yaml під k8s
+ * @param {(msg: string) => void} fail callback помилки
+ * @returns {Promise<void>}
+ */
+async function validateKustomizationIncludesSvcHlWithSvc(root, yamlFiles, fail) {
+  for (const kustAbs of yamlFiles) {
+    if (basename(kustAbs).toLowerCase() === 'kustomization.yaml') {
+      const rel = (relative(root, kustAbs) || kustAbs).replaceAll('\\', '/')
+      let raw
+      try {
+        raw = await readFile(kustAbs, 'utf8')
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error)
+        fail(`${rel}: не вдалося прочитати для перевірки svc.yaml/svc-hl.yaml у kustomization (${msg})`)
+      }
+      if (raw !== undefined) {
+        const lines = toLines(raw)
+        const body = yamlBodyAfterModeline(lines)
+        /** @type {import('yaml').Document[] | undefined} */
+        let docs
+        try {
+          docs = parseAllDocuments(body)
+        } catch {
+          fail(`${rel}: не вдалося розпарсити YAML для перевірки svc.yaml/svc-hl.yaml у kustomization (див. k8s.mdc)`)
+        }
+        if (docs !== undefined) {
+          const first = docs[0]?.toJSON()
+          if (first !== null && first !== undefined && typeof first === 'object' && !Array.isArray(first)) {
+            const pathRefs = pathsFromKustomizationObject(first)
+            const kustDir = dirname(kustAbs)
+            const v = kustomizationSvcYamlMissingSvcHlViolation(kustDir, pathRefs)
+            if (v !== null) {
+              fail(`${rel}: ${v}`)
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
 /**
  * Збирає відносні шляхи (posix) до YAML, підключених до Kustomize з будь-якого **`kustomization.yaml`** під `k8s`.
  * Обходить **`resources`**, **`bases`**, **`components`**, **`crds`**, **`patches[].path`**, **`patchesStrategicMerge`**;
@@ -420,6 +508,88 @@ async function findK8sYamlFiles(root) {
   return [...out].sort((a, b) => a.localeCompare(b))
 }
 
+/**
+ * Тіло YAML для політик (Ingress, BackendConfig тощо): якщо перший рядок — modeline `$schema`, береться вміст після нього.
+ * @param {string[]} lines рядки файлу
+ * @returns {string} фрагмент для `parseAllDocuments`
+ */
+function k8sYamlBodyForDocumentParse(lines) {
+  if (lines.length > 0 && MODELINE_RE.test(lines[0])) {
+    return yamlBodyAfterModeline(lines)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Чи всі нетривіальні документи у тілі — **`kind: BackendConfig`**, чи є змішування з іншими kind.
+ * @param {string} body YAML без обов’язкового modeline (див. `k8sYamlBodyForDocumentParse`)
+ * @returns {'none' | 'only' | 'mixed' | 'unparsed'} unparsed — не вдалося розпарсити YAML
+ */
+export function classifyBackendConfigManifestPresence(body) {
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(body)
+  } catch {
+    return 'unparsed'
+  }
+
+  let hasBc = false
+  let hasOther = false
+  for (const doc of docs) {
+    if (doc.errors.length === 0) {
+      const obj = doc.toJSON()
+      if (obj !== null && typeof obj === 'object' && !Array.isArray(obj)) {
+        const kind = obj.kind
+        if (kind === 'BackendConfig') {
+          hasBc = true
+        } else if (kind !== undefined && kind !== null && String(kind).trim() !== '') {
+          hasOther = true
+        }
+      }
+    }
+  }
+
+  if (!hasBc) return 'none'
+  if (hasOther) return 'mixed'
+  return 'only'
+}
+
+/**
+ * Видаляє під **`k8s`** YAML-файли, що містять **лише** ресурси **BackendConfig**; змішані файли — `fail`.
+ * @param {string} root корінь репозиторію
+ * @param {(msg: string) => void} fail реєстрація порушення
+ * @param {(msg: string) => void} pass реєстрація успіху
+ * @returns {Promise<void>}
+ */
+async function removeBackendConfigOnlyK8sYamlFiles(root, fail, pass) {
+  const yamlFiles = await findK8sYamlFiles(root)
+  for (const abs of yamlFiles) {
+    const rel = (relative(root, abs) || abs).replaceAll('\\', '/')
+    try {
+      const raw = await readFile(abs, 'utf8')
+      const lines = toLines(raw)
+      const body = k8sYamlBodyForDocumentParse(lines)
+      const bcPresence = classifyBackendConfigManifestPresence(body)
+
+      if (bcPresence === 'mixed') {
+        fail(
+          `${rel}: у файлі разом BackendConfig та інші kind — винеси BackendConfig окремо або прибери вручну; автоматичне видалення не застосовується (див. k8s.mdc)`
+        )
+      } else if (bcPresence === 'only') {
+        try {
+          await unlink(abs)
+          pass(`${rel}: видалено (лише kind: BackendConfig; див. k8s.mdc)`)
+        } catch (error) {
+          fail(`${rel}: не вдалося видалити BackendConfig-файл (${error.message})`)
+        }
+      }
+    } catch (error) {
+      fail(`${rel}: не вдалося прочитати для перевірки BackendConfig (${error.message})`)
+    }
+  }
+}
+
 /**
  * Прибирає BOM і ділить на рядки.
  * @param {string} content вміст файлу
@@ -441,6 +611,37 @@ function yamlBodyAfterModeline(lines) {
   return lines.slice(i).join('\n')
 }
 
+/**
+ * Читає k8s YAML і повертає фрагмент після modeline `$schema`, якщо перший рядок — modeline.
+ * Потрібно для парної перевірки **`svc.yaml`** / **`svc-hl.yaml`**.
+ * @param {string} abs абсолютний шлях до файлу
+ * @returns {Promise<string>} тіло для `parseAllDocuments`
+ */
+async function readK8sYamlBodyAfterModelineForSvcPair(abs) {
+  const raw = await readFile(abs, 'utf8')
+  const lines = toLines(raw)
+  if (lines.length > 0 && MODELINE_RE.test(lines[0])) {
+    return yamlBodyAfterModeline(lines)
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Розбирає YAML на корені документів-об’єктів (ігнорує зламані документи).
+ * @param {string} body фрагмент YAML
+ * @returns {unknown[]} масив об’єктів-документів
+ */
+function parseK8sYamlDocumentObjectRoots(body) {
+  try {
+    return parseAllDocuments(body)
+      .filter(d => d.errors.length === 0)
+      .map(d => d.toJSON())
+      .filter(x => x !== null && x !== undefined && typeof x === 'object' && !Array.isArray(x))
+  } catch {
+    return []
+  }
+}
+
 /**
  * Перший YAML-документ (до наступного `---` на окремому рядку).
  * @param {string} body фрагмент YAML
@@ -559,42 +760,6 @@ export function deploymentResourcesViolation(manifest) {
   return null
 }
 
-/**
- * Чи контейнери **Deployment** мають **`imagePullPolicy: Always`** (k8s.mdc).
- * @param {unknown} manifest корінь YAML-документа
- * @returns {string | null} текст порушення або null, якщо не Deployment / ок
- */
-export function deploymentImagePullPolicyViolation(manifest) {
-  if (manifest === null || manifest === undefined || typeof manifest !== 'object' || Array.isArray(manifest))
-    return null
-  const rec = /** @type {Record<string, unknown>} */ (manifest)
-  if (rec.kind !== 'Deployment') return null
-  const spec = rec.spec
-  if (spec === null || spec === undefined || typeof spec !== 'object' || Array.isArray(spec)) return null
-  const template = /** @type {Record<string, unknown>} */ (spec).template
-  if (template === null || template === undefined || typeof template !== 'object' || Array.isArray(template))
-    return null
-  const podSpec = /** @type {Record<string, unknown>} */ (template).spec
-  if (podSpec === null || podSpec === undefined || typeof podSpec !== 'object' || Array.isArray(podSpec)) return null
-  const containers = /** @type {Record<string, unknown>} */ (podSpec).containers
-  if (!Array.isArray(containers)) return null
-
-  for (const [i, c] of containers.entries()) {
-    const label =
-      typeof c === 'object' && c !== null && !Array.isArray(c) && typeof c.name === 'string' && c.name !== ''
-        ? c.name
-        : `#${i + 1}`
-    if (c !== null && c !== undefined && typeof c === 'object' && !Array.isArray(c)) {
-      const cont = /** @type {Record<string, unknown>} */ (c)
-      if (cont.imagePullPolicy !== 'Always') {
-        return `контейнер "${label}": imagePullPolicy має бути Always (див. k8s.mdc)`
-      }
-    }
-  }
-
-  return null
-}
-
 /**
  * Прибирає digest з посилання на образ (`@sha256:…`) для порівняння тега.
  * @param {string} image значення поля `image`
@@ -694,6 +859,287 @@ export function serviceForbiddenGcpAnnotationsViolation(manifest) {
   return `metadata.annotations: прибери заборонені ключі GKE: ${found.join(', ')} (див. k8s.mdc)`
 }
 
+/** Суфікс **`metadata.name`** headless-сервісу поруч із **`svc.yaml`** (див. k8s.mdc). */
+const SVC_HL_NAME_SUFFIX = '-hl'
+
+/**
+ * Kind маршрутів Gateway API, у **`spec`** яких шукаємо **`backendRefs`** / **`backendRef`** до **Service**.
+ * @type {Set<string>}
+ */
+const GATEWAY_API_ROUTE_KINDS = new Set(['HTTPRoute', 'GRPCRoute', 'TCPRoute', 'TLSRoute', 'UDPRoute'])
+
+/** Префікс **`apiVersion`** стандартних ресурсів Gateway API. */
+const GATEWAY_API_GROUP_PREFIX = 'gateway.networking.k8s.io/'
+
+/**
+ * Чи **Service** у **`svc.yaml`** має **`spec.type: ClusterIP`** (k8s.mdc).
+ * @param {unknown} manifest корінь YAML-документа
+ * @returns {string | null} текст порушення або null
+ */
+export function serviceSvcYamlClusterIpTypeViolation(manifest) {
+  if (manifest === null || manifest === undefined || typeof manifest !== 'object' || Array.isArray(manifest))
+    return null
+  const rec = /** @type {Record<string, unknown>} */ (manifest)
+  if (rec.kind !== 'Service') return null
+  const spec = rec.spec
+  if (spec === null || spec === undefined || typeof spec !== 'object' || Array.isArray(spec)) {
+    return 'Service: додай spec.type: ClusterIP (svc.yaml, див. k8s.mdc)'
+  }
+  const s = /** @type {Record<string, unknown>} */ (spec)
+  if (s.type !== 'ClusterIP') {
+    const cur = s.type === undefined ? 'відсутнє' : String(s.type)
+    return `Service spec.type має бути ClusterIP (svc.yaml; зараз: ${cur}; див. k8s.mdc)`
+  }
+  return null
+}
+
+/**
+ * Чи **Service** у **`svc-hl.yaml`** headless (**`spec.clusterIP: None`**) з суфіксом **`-hl`** у **`metadata.name`**.
+ * @param {unknown} manifest корінь YAML-документа
+ * @returns {string | null} текст порушення або null
+ */
+export function serviceSvcHlYamlHeadlessViolation(manifest) {
+  if (manifest === null || manifest === undefined || typeof manifest !== 'object' || Array.isArray(manifest))
+    return null
+  const rec = /** @type {Record<string, unknown>} */ (manifest)
+  if (rec.kind !== 'Service') return null
+  const meta = rec.metadata
+  if (meta === null || meta === undefined || typeof meta !== 'object' || Array.isArray(meta)) {
+    return 'Service: потрібні metadata.name з суфіксом -hl (svc-hl.yaml, див. k8s.mdc)'
+  }
+  const m = /** @type {Record<string, unknown>} */ (meta)
+  const n = m.name
+  if (typeof n !== 'string' || !n.endsWith(SVC_HL_NAME_SUFFIX)) {
+    return `Service metadata.name має закінчуватися на «${SVC_HL_NAME_SUFFIX}» (svc-hl.yaml; див. k8s.mdc)`
+  }
+  const spec = rec.spec
+  if (spec === null || spec === undefined || typeof spec !== 'object' || Array.isArray(spec)) {
+    return 'Service: додай spec.clusterIP: None (svc-hl.yaml, див. k8s.mdc)'
+  }
+  const s = /** @type {Record<string, unknown>} */ (spec)
+  if (s.clusterIP !== 'None') {
+    const cur = s.clusterIP === undefined ? 'відсутнє' : String(s.clusterIP)
+    return `Service spec.clusterIP має бути None (headless, svc-hl.yaml; зараз: ${cur}; див. k8s.mdc)`
+  }
+  return null
+}
+
+/**
+ * Чи об’єкт схожий на **backendRef** до **Kubernetes Service** у Gateway API.
+ * @param {unknown} obj вузол у дереві **`spec`**
+ * @returns {boolean} true, якщо враховуємо поле **`name`** як посилання на Service
+ */
+function isGatewayApiBackendRefToService(obj) {
+  if (obj === null || obj === undefined || typeof obj !== 'object' || Array.isArray(obj)) return false
+  const o = /** @type {Record<string, unknown>} */ (obj)
+  if (typeof o.name !== 'string') return false
+  const kind = o.kind
+  if (kind !== undefined && kind !== 'Service') return false
+  const group = o.group
+  if (typeof group === 'string' && group !== '' && group !== 'core') return false
+  return true
+}
+
+/**
+ * Збирає імена **Service** з **`backendRefs`** / **`backendRef`** у піддереві **`spec`** маршруту Gateway API.
+ * @param {unknown} spec значення **`spec`** маршруту
+ * @returns {string[]} імена backend-сервісів (можливі дублікати)
+ */
+export function collectGatewayApiRouteBackendServiceNames(spec) {
+  /** @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)) {
+      out.push(String(/** @type {Record<string, unknown>} */ (node).name))
+    }
+    for (const v of Object.values(node)) {
+      walk(v)
+    }
+  }
+
+  walk(spec)
+  return out
+}
+
+/**
+ * Реєструє порушення: маршрути Gateway API мають посилатися на **Service** з суфіксом **`-hl`**.
+ * @param {string} rel відносний шлях до файлу
+ * @param {string} body YAML після modeline
+ * @param {(msg: string) => void} fail callback помилки
+ * @returns {void}
+ */
+function scanGatewayApiRouteBackendRefsInYamlBody(rel, body, fail) {
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(body)
+  } catch {
+    return
+  }
+
+  for (const [di, doc] of docs.entries()) {
+    if (doc.errors.length === 0) {
+      const obj = doc.toJSON()
+      if (obj !== null && typeof obj === 'object' && !Array.isArray(obj)) {
+        const rec = /** @type {Record<string, unknown>} */ (obj)
+        const av = rec.apiVersion
+        const kind = rec.kind
+        if (
+          typeof av === 'string' &&
+          av.startsWith(GATEWAY_API_GROUP_PREFIX) &&
+          typeof kind === 'string' &&
+          GATEWAY_API_ROUTE_KINDS.has(kind)
+        ) {
+          const names = collectGatewayApiRouteBackendServiceNames(rec.spec)
+          for (const svcName of names) {
+            if (!svcName.endsWith(SVC_HL_NAME_SUFFIX)) {
+              fail(
+                `${rel}: Gateway API ${kind} (документ ${di + 1}): backendRef до Service має вказувати headless-сервіс з суфіксом «${SVC_HL_NAME_SUFFIX}» у name (зараз: «${svcName}»; див. k8s.mdc)`
+              )
+            }
+          }
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Перевіряє пари **`svc.yaml`** / **`svc-hl.yaml`** у каталозі (наявність, узгоджені імена **Service**).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlFiles абсолютні шляхи до `*.yaml` під `k8s`
+ * @param {(msg: string) => void} fail callback помилки
+ * @returns {Promise<void>}
+ */
+async function validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail) {
+  const absSet = new Set(yamlFiles)
+
+  for (const abs of yamlFiles) {
+    if (basename(abs).toLowerCase() === 'svc-hl.yaml') {
+      const svcAbs = join(dirname(abs), 'svc.yaml')
+      if (!absSet.has(svcAbs)) {
+        const rel = (relative(root, abs) || abs).replaceAll('\\', '/')
+        fail(`${rel}: svc-hl.yaml потребує svc.yaml у тому самому каталозі (див. k8s.mdc)`)
+      }
+    }
+  }
+
+  for (const svcAbs of yamlFiles) {
+    if (basename(svcAbs).toLowerCase() === 'svc.yaml') {
+      const rel = (relative(root, svcAbs) || svcAbs).replaceAll('\\', '/')
+      const hlAbs = join(dirname(svcAbs), 'svc-hl.yaml')
+      if (absSet.has(hlAbs)) {
+        /** @type {string | undefined} */
+        let svcBody
+        /** @type {string | undefined} */
+        let hlBody
+        try {
+          svcBody = await readK8sYamlBodyAfterModelineForSvcPair(svcAbs)
+          hlBody = await readK8sYamlBodyAfterModelineForSvcPair(hlAbs)
+        } catch (error) {
+          const msg = error instanceof Error ? error.message : String(error)
+          fail(`${rel}: не вдалося прочитати svc.yaml / svc-hl.yaml (${msg})`)
+        }
+        if (svcBody !== undefined && hlBody !== undefined) {
+          const svcRoots = parseK8sYamlDocumentObjectRoots(svcBody)
+          const hlRoots = parseK8sYamlDocumentObjectRoots(hlBody)
+
+          /** @type {string[]} */
+          const svcNames = []
+          for (const [i, rootObj] of svcRoots.entries()) {
+            const r = /** @type {Record<string, unknown>} */ (rootObj)
+            if (r.kind === 'Service') {
+              const meta = r.metadata
+              if (meta !== null && typeof meta === 'object' && !Array.isArray(meta)) {
+                const nm = /** @type {Record<string, unknown>} */ (meta).name
+                if (typeof nm === 'string') {
+                  svcNames.push(nm)
+                } else {
+                  fail(`${rel}: svc.yaml (документ ${i + 1}): Service без metadata.name (див. k8s.mdc)`)
+                }
+              } else {
+                fail(`${rel}: svc.yaml (документ ${i + 1}): Service без metadata (див. k8s.mdc)`)
+              }
+            }
+          }
+
+          if (svcNames.length === 0) {
+            fail(`${rel}: svc.yaml має містити принаймні один kind: Service (див. k8s.mdc)`)
+          } else {
+            /** @type {string[]} */
+            const hlNames = []
+            for (const [i, rootObj] of hlRoots.entries()) {
+              const r = /** @type {Record<string, unknown>} */ (rootObj)
+              if (r.kind === 'Service') {
+                const meta = r.metadata
+                if (meta !== null && typeof meta === 'object' && !Array.isArray(meta)) {
+                  const nm = /** @type {Record<string, unknown>} */ (meta).name
+                  if (typeof nm === 'string') {
+                    hlNames.push(nm)
+                  } else {
+                    const hlRel = (relative(root, hlAbs) || hlAbs).replaceAll('\\', '/')
+                    fail(`${hlRel}: svc-hl.yaml (документ ${i + 1}): Service без metadata.name (див. k8s.mdc)`)
+                  }
+                } else {
+                  const hlRel = (relative(root, hlAbs) || hlAbs).replaceAll('\\', '/')
+                  fail(`${hlRel}: svc-hl.yaml (документ ${i + 1}): Service без metadata (див. k8s.mdc)`)
+                }
+              }
+            }
+
+            if (hlNames.length === 0) {
+              const hlRel = (relative(root, hlAbs) || hlAbs).replaceAll('\\', '/')
+              fail(`${hlRel}: svc-hl.yaml має містити принаймні один kind: Service (див. k8s.mdc)`)
+            } else {
+              const hlSet = new Set(hlNames)
+              for (const n of svcNames) {
+                const expectHl = `${n}${SVC_HL_NAME_SUFFIX}`
+                if (!hlSet.has(expectHl)) {
+                  fail(
+                    `${rel}: для Service «${n}» у svc.yaml у svc-hl.yaml має бути Service з metadata.name «${expectHl}» (див. k8s.mdc)`
+                  )
+                }
+              }
+
+              for (const h of hlNames) {
+                if (h.endsWith(SVC_HL_NAME_SUFFIX)) {
+                  const base = h.slice(0, -SVC_HL_NAME_SUFFIX.length)
+                  if (!svcNames.includes(base)) {
+                    const hlRel = (relative(root, hlAbs) || hlAbs).replaceAll('\\', '/')
+                    fail(
+                      `${hlRel}: Service «${h}» у svc-hl.yaml не відповідає жодному Service у svc.yaml (очікується базове ім’я «${base}»; див. k8s.mdc)`
+                    )
+                  }
+                } else {
+                  const hlRel = (relative(root, hlAbs) || hlAbs).replaceAll('\\', '/')
+                  fail(
+                    `${hlRel}: Service «${h}» у svc-hl.yaml: metadata.name має закінчуватися на «${SVC_HL_NAME_SUFFIX}» (див. k8s.mdc)`
+                  )
+                }
+              }
+            }
+          }
+        }
+      } else {
+        fail(`${rel}: поруч обов’язковий svc-hl.yaml (headless-копія з суфіксом -hl у metadata.name; див. k8s.mdc)`)
+      }
+    }
+  }
+}
+
 /**
  * Для маніфестів, **підключених** до Kustomize (шлях у `resources` / `patches` / …), **metadata.namespace** не додають.
  * @param {unknown} manifest корінь YAML-документа
@@ -762,8 +1208,9 @@ export function isK8sBaseManifestYamlPath(rel, baseLower) {
 }
 
 /**
- * Парсить усі YAML-документи: **metadata.namespace**, **Deployment.resources**, **imagePullPolicy**, **Hasura image pin**,
- * **Service — заборонені GKE-анотації**.
+ * Парсить усі YAML-документи: **metadata.namespace**, **Deployment.resources**, **Hasura image pin**,
+ * **Service — заборонені GKE-анотації**, **`svc.yaml`** (**`spec.type: ClusterIP`**), **`svc-hl.yaml`**
+ * (**headless**, суфікс **`-hl`** у **`metadata.name`**).
  * @param {string} rel відносний шлях
  * @param {string} baseLower basename файлу (нижній регістр)
  * @param {string} body вміст після modeline
@@ -811,10 +1258,6 @@ function validateK8sYamlPolicyDocuments(rel, baseLower, body, fail, kustomizeMan
       if (resV !== null) {
         fail(`${rel}: Deployment (документ ${di + 1}): ${resV}`)
       }
-      const pullV = deploymentImagePullPolicyViolation(obj)
-      if (pullV !== null) {
-        fail(`${rel}: Deployment (документ ${di + 1}): ${pullV}`)
-      }
       const hasuraV = deploymentHasuraGraphqlEngineImageViolation(obj)
       if (hasuraV !== null) {
         fail(`${rel}: Deployment (документ ${di + 1}): ${hasuraV}`)
@@ -823,6 +1266,18 @@ function validateK8sYamlPolicyDocuments(rel, baseLower, body, fail, kustomizeMan
       if (svcGcpV !== null) {
         fail(`${rel}: Service (документ ${di + 1}): ${svcGcpV}`)
       }
+      if (baseLower === 'svc.yaml') {
+        const svcT = serviceSvcYamlClusterIpTypeViolation(obj)
+        if (svcT !== null) {
+          fail(`${rel}: Service (документ ${di + 1}): ${svcT}`)
+        }
+      }
+      if (baseLower === 'svc-hl.yaml') {
+        const svcH = serviceSvcHlYamlHeadlessViolation(obj)
+        if (svcH !== null) {
+          fail(`${rel}: Service (документ ${di + 1}): ${svcH}`)
+        }
+      }
     }
   }
 }
@@ -975,6 +1430,8 @@ async function checkK8sYamlFile(abs, root, fail, pass, kustomizeManagedRel) {
 
   const kustomizeManaged = kustomizeManagedRel.has(rel)
   validateK8sYamlPolicyDocuments(rel, baseLower, body, fail, kustomizeManaged)
+
+  scanGatewayApiRouteBackendRefsInYamlBody(rel, body, fail)
 }
 
 /**
@@ -1042,6 +1499,9 @@ export async function check() {
   }
 
   const root = process.cwd()
+
+  await removeBackendConfigOnlyK8sYamlFiles(root, fail, pass)
+
   const yamlFiles = await findK8sYamlFiles(root)
 
   if (yamlFiles.length === 0) {
@@ -1059,6 +1519,10 @@ export async function check() {
     await checkK8sYamlFile(abs, root, fail, pass, kustomizeManagedRel)
   }
 
+  await validateSvcYamlAndSvcHlPairs(root, yamlFiles, fail)
+
+  await validateKustomizationIncludesSvcHlWithSvc(root, yamlFiles, fail)
+
   await ensureBaseKustomizationHasNamespace(root, yamlFiles, fail)
 
   return exitCode

package/skills/abie-kustomize/SKILL.md

@@ -21,6 +21,4 @@ README має бути в директорії **k8s**.
 
 Застарілі файли прибирай.
 
-У всіх Deployment має бути `imagePullPolicy: Always`.
-
 Для overlays **ru** та **ua** `namespace` задавай у `kustomization.yaml` (без окремих patch лише на зміну namespace). Деталі — **n-k8s** / **abie** у `.cursor/rules/`, якщо ці правила увімкнені в проєкті.