@nitra/cursor 1.8.61 → 1.8.64

package/mdc/k8s.mdc

@@ -42,7 +42,7 @@ alwaysApply: false
 }
 ```
 
-Якщо правило **`k8s`** підключено в **`.n-cursor.json`** (масив **`rules`**), у **кореневому** `package.json` **обов'язково** мають бути скрипт **`lint-k8s`** і виклик **`bun run lint-k8s`** у агрегованому **`lint`** (див. **`bun.mdc`**). Це перевіряє **`npx @nitra/cursor check bun`**.
+Якщо правило **`k8s`** підключено в **`.n-cursor.json`** (масив **`rules`**), у **кореневому** `package.json` **мають** бути скрипт **`lint-k8s`** і виклик **`bun run lint-k8s`** у агрегованому **`lint`** (див. **`bun.mdc`**). Це перевіряє **`npx @nitra/cursor check bun`**.
 
 Шлях до скрипта підстав свій (`./scripts/…` після копіювання, `node_modules/@nitra/cursor/scripts/…` якщо пакет у залежностях).
 
@@ -96,26 +96,25 @@ jobs:
 
 ## Deployment: `resources`
 
-Для **`kind: Deployment`** у кожному контейнері **`spec.template.spec.containers[]`** має бути явне поле **`resources`**. Якщо ліміти та requests ще не задані, додай порожній об'єкт:
+У **`Deployment`** у кожному **`containers`** / **`initContainers`** має бути **`resources`**; якщо лімітів ще немає — мінімум порожній запис:
 
 ```yaml
 resources: {}
 ```
 
-Так маніфест явно резервує місце під **`requests` / `limits`** і уникає випадкового пропуску секції. **`check k8s`** перевіряє це для кожного YAML-документа **`Deployment`** у файлах під **`k8s`**.
+**`check k8s`** перевіряє наявність **`resources`** у кожному документі **Deployment** під **`k8s`**. Поле **`imagePullPolicy`** скрипт **не** перевіряє (залишається політиці Kubernetes за тегом образу).
 
-**`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`**.
+Образ **`hasura/graphql-engine`**: дозволений лише канонічний тег із константи **`HASURA_GRAPHQL_ENGINE_IMAGE`** у **`check-k8s.mjs`** (допускається префікс **`docker.io/`**); решта — помилка **check k8s**.
 
 ## Service: заборонені анотації GKE
 
-У **`kind: Service`** не використовуй у **`metadata.annotations`** ключі:
+У **`kind: Service`** не додавай у **`metadata.annotations`** **`cloud.google.com/neg`** і **`cloud.google.com/backend-config`** (legacy під Ingress / старе балансування GKE). **check k8s** падає, якщо ключ є.
+
+## Service: `svc.yaml` і `svc-hl.yaml` (Gateway API)
 
-- **`cloud.google.com/neg`**
-- **`cloud.google.com/backend-config`**
+Пара файлів для кластерного й headless **Service**: **`svc.yaml`** + **`svc-hl.yaml`** в одному каталозі, **`spec.type: ClusterIP`** / **`clusterIP: None`**, імена **`-hl`**, узгодженість пар, маршрути **`gateway.networking.k8s.io`** (**HTTPRoute**, **GRPCRoute**, **TCPRoute**, **TLSRoute**, **UDPRoute**) — **backendRef** лише на сервіси з суфіксом **`-hl`**; якщо **kustomization** посилається на **`svc.yaml`**, у **тому ж** **`kustomization.yaml`** має бути посилання на sibling **`svc-hl.yaml`**. Скрипт **не** створює файли — додай **`svc-hl.yaml`** вручну (копія з правками **name** / **clusterIP**).
 
-Вони потрібні для інтеграції з **Ingress** / класичним балансуванням GKE; після переходу на **Gateway API** їх слід **прибрати** з маніфестів. **`check k8s`** завершиться помилкою, якщо хоча б один із цих ключів присутній.
+**Точні умови та повідомлення `fail`** — верхній JSDoc **`npm/scripts/check-k8s.mjs`**.
 
 ## Kustomize: структура каталогів (`base` / overlays)
 
@@ -134,11 +133,11 @@ resources: {}
 
 ### Namespace
 
-- **`base/kustomization.yaml`:** у цьому файлі поле **`namespace:`** **завжди** має бути присутнє й **непорожнє**, щоб Kustomize застосував один цільовий namespace до ресурсів **base**. **`check k8s`** перевіряє це, коли файл є в репозиторії.
+- **`base/kustomization.yaml`:** поле **`namespace:`** має бути **непорожнім** (перевіряє **check k8s**, якщо файл є).
 
-- **Де не дублювати `metadata.namespace`:** у YAML під **`k8s`**, чиї шляхи **досяжні** з будь-якого **`kustomization.yaml`** через **`resources`**, **`bases`**, **`components`**, **`crds`**, елементи **`patches`** з полем **`path`**, **`patchesStrategicMerge`** (транзитивно, зокрема через каталог із дочірнім **`kustomization.yaml`**). У таких файлах **не** вказуй **`metadata.namespace`** — його виставляє Kustomize за полем **`namespace:`** у kustomization.
+- **Де не дублювати `metadata.namespace`:** у YAML, досяжних через **граф Kustomize** (шляхи з **`kustomization.yaml`**, як у логіці **`collectKustomizeManagedRelPaths`** / **check k8s**). **Namespace** задає **`namespace:`** у kustomization.
 
-- **Коли `metadata.namespace` обов’язковий:** YAML під **`k8s`**, який **ніде** не перелічений у згаданих полях жодного kustomization-файлу, має містити **непорожній** **`metadata.namespace`** у кожному документі з **`apiVersion`** та **`kind`**, **окрім** кластерних ресурсів (наприклад **`Namespace`**, **`ClusterRole`**, **`PersistentVolume`** — повний перелік у **`check-k8s.mjs`**, **`CLUSTER_SCOPED_KINDS`**). Якщо файл має бути без namespace у маніфесті — підключи його до kustomization через **`resources`** / **`patches`** тощо.
+- **Коли `metadata.namespace` обов’язковий у файлі:** YAML під **`k8s`**, який **не** в графі жодного kustomization — непорожній **`metadata.namespace`** для namespaced **kind** (винятки — кластерні **kind**, перелік **`CLUSTER_SCOPED_KINDS`** у **`check-k8s.mjs`**). Якщо namespace у маніфесті не потрібен — підключи файл через **`resources`** / **`patches`** тощо.
 
 - **Не додавай** окремі **patches** Kustomize, які лише змінюють **namespace**: **namespace** визначає Kustomize; у overlays додаткові зміни — без дублювання логіки **namespace**.
 
@@ -174,27 +173,56 @@ resources: {}
 
 **`check k8s`:** заборонено **`kind: Ingress`**.
 
-## Перевірка
+3. Якщо **HTTPRoute** посилається на **Service** в іншому **namespace**, потрібен **ReferenceGrant** (дозвіл). Наприклад **HTTPRoute** в **`contract`** і **Service** в **`dev`** — додай маніфест на кшталт **`base/rg.yaml`** (фрагмент нижче).
+
+```yaml title="base/rg.yaml"
+# yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/gateway.networking.k8s.io/referencegrant_v1beta1.json
+apiVersion: gateway.networking.k8s.io/v1beta1
+kind: ReferenceGrant
+metadata:
+  name: contract-to-dev
+  namespace: dev
+spec:
+  from:
+    - group: gateway.networking.k8s.io
+      kind: HTTPRoute
+      namespace: contract
+  to:
+    - group: ''
+      kind: Service
+      # Якщо name не вказано, доступ дозволено до всіх Service в цьому namespace
+```
 
-**`npx @nitra/cursor check k8s`** — деталі умов у **JSDoc на початку** **`npm/scripts/check-k8s.mjs`**; канон URL **`$schema`** для редактору — розділ **«Визначення схеми YAML»** нижче. Якщо під `k8s` немає `*.yaml` — перевірку пропущено. Решту політик кластера / compliance закриває **`lint-k8s`**.
+**ReferenceGrant** має бути в **namespace** тих **Service**, до яких відкривається доступ (у прикладі — **`dev`**). Якщо **`namespace:`** у **overlay** не збігається з **namespace** гранта, **не** додавай **`base/rg.yaml`** у **`resources:`** того overlay — Kustomize може перезаписати **`metadata.namespace`** гранта. Натомість застосуй **`patches`** (JSON patch), щоб явно виставити потрібний **namespace**:
+
+```yaml title="overlay/kustomization.yaml (фрагмент)"
+patches:
+  - target:
+      kind: ReferenceGrant
+      name: contract-to-dev
+    patch: |-
+      - op: replace
+        path: /metadata/namespace
+        value: dev
+```
+
+## Перевірка
 
-Після змін у маніфестах: **`bun run lint-k8s`** (kubeconform + kubescape).
+**`npx @nitra/cursor check k8s`** — програмні критерії в **JSDoc на початку** **`npm/scripts/check-k8s.mjs`**. Якщо під **`k8s`** немає **`*.yaml`** — крок пропущено. Канон **`$schema`** для редактора — розділ **«Визначення схеми YAML`** нижче.
 
-## Що закодовано в `check-k8s.mjs`
+**Не входить у check k8s:** наприклад **ReferenceGrant** і доступ між **namespace** (лише рекомендації тут), **kubeconform** / **kubescape** — це **`bun run lint-k8s`**.
 
-Не дублюй тут повний перелік — він у **верхньому JSDoc** **`npm/scripts/check-k8s.mjs`** і в константах (**`YANNH_PIN`**, **`YANNH_GROUPS`**, **`EXPLICIT_K8S_SCHEMAS`**, **`CLUSTER_SCOPED_KINDS`**, **`HASURA_GRAPHQL_ENGINE_IMAGE`** тощо).
+## Що саме в скрипті `check-k8s.mjs`
 
-Коротко: **`$schema`** (один modeline, без **`.yml`** під **`k8s`**), заборона **Ingress**, **Deployment.resources**, пін **hasura/graphql-engine**, **Service** без анотацій NEG/backend-config, **`metadata.namespace`** залежно від **base** і графа Kustomize, заборона **`…/k8s/dev/…`**, непорожній **`namespace:`** у **`k8s/base/kustomization.yaml`**, видалення файлів, де всі документи — лише **BackendConfig** (змішані файли — помилка).
+Повний перелік умов, константи (**`YANNH_PIN`**, **`CLUSTER_SCOPED_KINDS`**, **`HASURA_GRAPHQL_ENGINE_IMAGE`** тощо) і допоміжні функції — у файлі скрипта; змінив вимогу для **check** — онови **JSDoc** і за потреби тести в **`npm/tests/check-k8s-schema.test.mjs`**.
 
-При зміні **PIN** версії Kubernetes оновлюй узгоджено **`check-k8s.mjs`**, **`run-k8s.mjs`** (**`KUBERNETES_VERSION`**, **`DATREE_CRD_SCHEMA_LOCATION`**) і розділи **lint-k8s** / **Визначення схеми YAML** у цьому файлі (**`YANNH_REF`**, **`YANNH_GROUPS`**, **`DATREE_CRD_BASE`** — за потреби в скрипті).
+При зміні **PIN** версії Kubernetes узгодь **`check-k8s.mjs`**, **`run-k8s.mjs`** (**`KUBERNETES_VERSION`**, **`DATREE_CRD_SCHEMA_LOCATION`**) і цей файл (**lint-k8s**, **Визначення схеми YAML**).
 
 ## Коли застосовувати (агентам)
 
-- Зміни в k8s YAML — після правок **`check k8s`**.
-- Якщо перший рядок уже коректний і URL відповідає `apiVersion` / `kind` — не дублюй; змінився ресурс — онови лише `$schema`.
-- У **`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`**.
-- Після міграції на нову структуру **видали** застарілі файли та каталоги, які вже замінені (див. **Міграція зі старої структури**).
+- Після змін у k8s YAML: **`npx @nitra/cursor check k8s`** і за наявності правила — **`bun run lint-k8s`**.
+- Оновив **`apiVersion` / `kind`** — підправ **перший** рядок **`$schema`** (див. **Визначення схеми YAML**).
+- Дотримуйся **Kustomize** з цього правила; деталі **namespace** / графа ресурсів — **check k8s** + підказки в JSDoc скрипта.
 
 ## Визначення схеми YAML (канон)
 

package/package.json

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

package/scripts/check-k8s.mjs

@@ -6,9 +6,9 @@
  * (datree за замовчуванням: GitHub Pages `https://datreeio.github.io/CRDs-catalog/…`).
  *
  * Додатково: у кожному YAML-документі з **`kind: Deployment`** у кожного контейнера
- * **`spec.template.spec.containers[]`** має бути ключ **`resources`** (значення — об'єкт, допускається
+ * **`spec.template.spec.containers[]`** має бути ключ **`resources`** (значення — об’єкт, допускається
  * порожній **`{}`**). Поле **`imagePullPolicy`** не перевіряється — діють типові правила Kubernetes
- * (`:latest` або без тега → **Always**, інші теги → **IfNotPresent**). Якщо серед **`containers`** /
+ * (`:latest` або коли тег не вказано → **Always**, інші теги → **IfNotPresent**). Якщо серед **`containers`** /
  * **`initContainers`** є образ **`hasura/graphql-engine`**, дозволено лише пін **`HASURA_GRAPHQL_ENGINE_IMAGE`**
  * (див. k8s.mdc).
  *
@@ -27,6 +27,16 @@
  * У **`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:`** (перевірка, якщо файл існує).
  *
@@ -296,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`**;
@@ -439,7 +522,6 @@ function k8sYamlBodyForDocumentParse(lines) {
 
 /**
  * Чи всі нетривіальні документи у тілі — **`kind: BackendConfig`**, чи є змішування з іншими kind.
- *
  * @param {string} body YAML без обов’язкового modeline (див. `k8sYamlBodyForDocumentParse`)
  * @returns {'none' | 'only' | 'mixed' | 'unparsed'} unparsed — не вдалося розпарсити YAML
  */
@@ -475,7 +557,6 @@ export function classifyBackendConfigManifestPresence(body) {
 
 /**
  * Видаляє під **`k8s`** YAML-файли, що містять **лише** ресурси **BackendConfig**; змішані файли — `fail`.
- *
  * @param {string} root корінь репозиторію
  * @param {(msg: string) => void} fail реєстрація порушення
  * @param {(msg: string) => void} pass реєстрація успіху
@@ -530,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[]} масив успішно розібраних коренів YAML-документів
+ */
+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
@@ -610,7 +722,7 @@ function scanIngressInYamlDocuments(rel, body, fail) {
 
 /**
  * Чи порушує маніфест вимогу **`Deployment.spec.template.spec.containers[].resources`** (див. k8s.mdc).
- * @param {unknown} manifest корінь YAML-документа як об'єкт JavaScript
+ * @param {unknown} manifest корінь YAML-документа як запис JavaScript
  * @returns {string | null} текст порушення для `fail` або null, якщо перевірка не застосовується / ок
  */
 export function deploymentResourcesViolation(manifest) {
@@ -640,7 +752,7 @@ export function deploymentResourcesViolation(manifest) {
       }
       const r = cont.resources
       if (r === null || typeof r !== 'object' || Array.isArray(r)) {
-        return `контейнер "${label}": resources має бути об'єктом (наприклад порожній об'єкт у YAML: resources: {})`
+        return `контейнер "${label}": resources має бути записом у YAML (наприклад порожній: resources: {})`
       }
     }
   }
@@ -649,7 +761,7 @@ export function deploymentResourcesViolation(manifest) {
 }
 
 /**
- * Прибирає digest з посилання на образ (`@sha256:…`) для порівняння тега.
+ * Прибирає digest з посилання на образ (`@sha256:…`) для порівняння тегу образу.
  * @param {string} image значення поля `image`
  * @returns {string} той самий рядок без суфікса `@…` (digest), з `.trim()`
  */
@@ -659,7 +771,7 @@ function stripImageDigest(image) {
 }
 
 /**
- * Чи рядок `image` вказує на репозиторій **hasura/graphql-engine** (будь-який тег / без тега).
+ * Чи рядок `image` вказує на репозиторій **hasura/graphql-engine** (будь-який тег / без вказаного тегу).
  * @param {string} image значення поля `image`
  * @returns {boolean} true, якщо шлях образу закінчується на `hasura/graphql-engine` з тегом або без
  */
@@ -696,7 +808,7 @@ function hasuraGraphqlEngineViolationInContainerList(list, containers) {
 }
 
 /**
- * Чи порушує **Deployment** вимогу пінованого образу **hasura/graphql-engine** (k8s.mdc).
+ * Чи порушує **Deployment** вимогу щодо зафіксованого образу **hasura/graphql-engine** (k8s.mdc).
  * @param {unknown} manifest корінь YAML-документа
  * @returns {string | null} текст порушення або null, якщо не Deployment / образу немає / ок
  */
@@ -747,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-документа
@@ -816,7 +1209,8 @@ export function isK8sBaseManifestYamlPath(rel, baseLower) {
 
 /**
  * Парсить усі YAML-документи: **metadata.namespace**, **Deployment.resources**, **Hasura image pin**,
- * **Service — заборонені GKE-анотації**.
+ * **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
@@ -872,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}`)
+        }
+      }
     }
   }
 }
@@ -1024,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)
 }
 
 /**
@@ -1111,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