@nitra/cursor 12.8.5 → 12.8.7

package/rules/k8s/js/hpa_apiversion.mdc

@@ -0,0 +1,27 @@
+## HorizontalPodAutoscaler: `autoscaling/v2`
+
+У manifest-файлах під **`k8s`** заборонено **`apiVersion: autoscaling/v1`** (legacy HPA з єдиною метрикою CPU). Мігруй **HorizontalPodAutoscaler** на **`autoscaling/v2`**: поле **`spec.metrics`** (замість **`spec.targetCPUUtilizationPercentage`**) з **`type: Resource`** і **`target.type: Utilization`** / **`AverageUtilization`**. `check k8s` падає на будь-якому документі з **`apiVersion: autoscaling/v1`**.
+
+Ресурси **batch** (наприклад **CronJob**, **Job**): застаріле **`apiVersion: batch/v1beta1`** у файлах під **`k8s`** під час `check k8s` переписується на **`apiVersion: batch/v1`**.
+
+```yaml
+# yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/horizontalpodautoscaler-autoscaling-v2.json
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: app
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: app
+  minReplicas: 1
+  maxReplicas: 5
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+```

package/rules/k8s/js/ingress_gateway.mdc

@@ -0,0 +1,16 @@
+## Ingress → Gateway API (GKE)
+
+Якщо в дереві **`k8s`** трапляється маніфест з **`kind: Ingress`**, його потрібно **замінити на Gateway API**, а не залишати Ingress. **`check k8s`:** заборонено **`kind: Ingress`**.
+
+1. **HTTPRoute** — окремий файл **`hr.yaml`** (або узгоджене ім'я в команді), **`kind: HTTPRoute`**, `apiVersion` з групи **`gateway.networking.k8s.io`**.
+
+2. **HealthCheckPolicy (GKE)** — окремий файл **`hc.yaml`**:
+
+   ```yaml
+   apiVersion: networking.gke.io/v1
+   kind: HealthCheckPolicy
+   ```
+
+   Для `$schema` у першому рядку — приклад **HealthCheckPolicy** у розділі «Визначення схеми YAML» (datree CRDs-catalog).
+
+   **`spec.targetRef`** (типово **`kind: Service`**) має вказувати на **headless** сервіс — ім'я з суфіксом **`-hl`** (div. **«Service: `svc.yaml` і `svc-hl.yaml`»**).

package/rules/k8s/js/kustomize_structure.mdc

@@ -0,0 +1,144 @@
+## Kustomize: структура каталогів (`base` / overlays)
+
+Трансформуй дерева **`**/k8s`**, щоб **винести спільне** через [Kustomize](https://kustomize.io/): один канонічний **`base`** і тонкі **overlays** для інших середовищ.
+
+### Джерело правди — середовище dev
+
+- За основу бери **все, що відповідає середовищу dev** (як воно має виглядати в кластері для dev).
+- У **такому вигляді** цей набір стає каталогом **`base`**: спільні маніфести без окремої директорії **`dev/`**.
+- Окремої директорії **`dev`** **не повинно існувати**: за середовище **dev** відповідає **`base`**.
+
+### Overlays (не-dev)
+
+- У каталозі кожного іншого середовища (наприклад **`ua/`**, **`prod/`**) — мінімум файлів: типово лише **`kustomization.yaml`** і ресурси, **необхідні лише для цього overlay**.
+- Відмінності від dev вносяться **оверрайдами** (patches, `images`, `replicas`, `configMapGenerator` тощо), а не копіюванням повного дерева з `base`.
+
+### Namespace
+
+- **`base/kustomization.yaml`:** поле **`namespace:`** має бути **непорожнім** (перевіряє **check k8s**).
+- **Коли `metadata.namespace` обов'язковий у файлі:** YAML під **`k8s`** — непорожній **`metadata.namespace`** для namespaced **kind** (винятки — кластерні **kind**, перелік **`CLUSTER_SCOPED_KINDS`** у **`rules/k8s/fix.mjs`**).
+- **Не додавай** окремі **patches** Kustomize, які лише змінюють **namespace**.
+
+### Рядки, що змінюються між середовищами
+
+У manifest-файлах у **`base`** для полів, які **будуть відрізнятися** в інших середовищах, на **тому самому рядку** додай коментар:
+
+```yaml
+image: my-app:dev-tag # буде замінено через kustomize
+```
+
+### Зміна image — через `images:`, не через `patches[]`
+
+Підміну image у Pod-шаблоні Deployment в overlay роби директивою `images:`, а не JSON6902-патчем `op: replace` на `/spec/template/spec/containers/<N>/image`.
+
+- У **`name`** — те, що **дослівно** стоїть у `image:` у base **без тегу**.
+- **`newName`** — кінцеве ім'я образу; **`newTag`** — тег для прода.
+- **`digest`** (`@sha256:…`) у `name` / `newName` не чіпай.
+
+```yaml title="k8s/prod/kustomization.yaml (фрагмент)"
+images:
+  - name: europe-west4-docker.pkg.dev/abie-ua/c/apply-on-invoice-discount
+    newName: europe-west4-docker.pkg.dev/abie-ua/c/apply-on-invoice-discount
+    newTag: v2025-04-29
+```
+
+**`check k8s` автоматично** для кожного `kustomization.yaml`:
+
+1. конвертує кожну JSON6902-операцію `op: replace` на `/spec/template/spec/containers/<N>/image` у запис `images:`;
+2. чистить існуючий блок `images:` — зрізає `:tag` з `name` і видаляє `newTag`, який збігається з відрізаним тегом.
+
+### Міграція зі старої структури
+
+Після перенесення у **`base`** та overlays і перевірки (**`check k8s`**, **`lint-k8s`**) **видали** застарілі файли та директорії, що замінені новою схемою.
+
+### `patches[].target`: лише `kind` і `name`
+
+У `patches[].target` залишай **тільки** **`kind`** і **`name`** — поля **`group`** і **`version`** прибирай.
+
+```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-групами/версіями.
+
+### Структурний сорт `patches[]` і inline JSON6902
+
+`patches[]` у `kustomization.yaml` має бути відсортовано за tuple **`target.kind` → `target.name` → `target.namespace` → `path`** (`localeCompare('en', { sensitivity: 'base' })`).
+
+```yaml
+# ❌ atlas йде перед apruv
+patches:
+  - target:
+      kind: ReferenceGrant
+      name: atlas-to-base
+  - target:
+      kind: ReferenceGrant
+      name: apruv-to-base
+
+# ✅
+patches:
+  - target:
+      kind: ReferenceGrant
+      name: apruv-to-base
+  - target:
+      kind: ReferenceGrant
+      name: atlas-to-base
+```
+
+Усередині кожного inline `patches[i].patch` операції теж сортуються за **`path`**, **але лише** коли набір «безпечний»: усі ops — `add` / `replace` і всі `path` попарно дизʼюнктні. Інакше порядок не чіпається.
+
+```yaml
+# ❌ minReplicas перед maxReplicas (за алфавітом max < min)
+patch: |-
+  - op: add
+    path: /spec/minReplicas
+    value: 2
+  - op: replace
+    path: /spec/maxReplicas
+    value: 10
+
+# ✅
+patch: |-
+  - op: replace
+    path: /spec/maxReplicas
+    value: 10
+  - op: add
+    path: /spec/minReplicas
+    value: 2
+```
+
+### Порядок `resources`
+
+Елементи **`resources:`** (лише непорожні рядки) мають бути **відсортовані за алфавітом (англ. локаль, як `localeCompare('en')` у `rules/k8s/fix.mjs`)**. Поля **`bases`**, **`components`**, **`crds`** цією перевіркою **не** впорядковуються.
+
+### Локальні шляхи в `kustomization.yaml`
+
+Кожен запис без `://` (remote) з `resources` / `bases` / `components` / `crds`, `patchesStrategicMerge`, `patches[].path`, `patchesJson6902[].path`, `configurations[]`, `replacements[].path` має вказувати на **існуючий** у репозиторії файл (`.yaml` / `.yml`) або **каталог**; биті посилання — помилка **`check k8s`**.
+
+### JSON patch у kustomization: `op: replace`
+
+Де можливо, змінюй ресурс через **`op: replace`** (одна операція на `path`), а не пару **`remove` + `add`** на той самий шлях.
+
+```yaml title="overlay/kustomization.yaml (фрагмент)"
+patches:
+  - target:
+      kind: Deployment
+      name: x
+    patch: |-
+      - op: replace
+        path: /spec/template/spec/nodeSelector
+        value:
+          preem: "false"
+```

package/rules/k8s/js/lint_k8s.mdc

@@ -0,0 +1,72 @@
+## lint-k8s: kubeconform і kubescape
+
+Окремо від modeline `$schema` у редакторі варто ганяти CLI-лінтери (**kubeconform** і **kubescape**) по тих самих деревах **`…/k8s`**.
+
+**Залежності:** виконувані файли kubeconform, kubescape і kubectl у **PATH** (kustomize використовуємо як вшиту підкоманду **`kubectl kustomize`** — окремий бінарник `kustomize` не потрібен); не додавай їх у **devDependencies**.
+
+**Версія Kubernetes для kubeconform** — **`-kubernetes-version 1.33.9`** (semver без префікса `v`; набір схем **`v1.33.9-standalone-strict`**). Для CRD додатково підключай реєстр [datreeio/CRDs-catalog](https://github.com/datreeio/CRDs-catalog) другим **`-schema-location`**. За потреби **`-ignore-missing-schemas`**.
+
+**kubescape** — вхід через зібраний kustomize-маніфест: для кожного dir-у з `kustomization.yaml` (`kind: Kustomization`; **`kind: Component`** пропускається) `lint-k8s` виконує **`kubectl kustomize <dir>`** і передає stdout у **`kubescape scan <tmp-file>`** з порогом **`--severity-threshold high`**. Маніфест проходить через тимчасовий файл, бо **`kubescape scan` у v4.x не читає stdin**. Якщо в дереві **`…/k8s`** немає жодного `kustomization.yaml` — fallback на dir-скан **`kubescape scan <каталог-k8s>`**. У kubescape немає прапорця **`-kubernetes-version`**.
+
+Лінт запускається через правило **`n-cursor lint k8s`** (реалізація — **`npm/rules/k8s/js/lint.mjs`**). Окремий `package.json`-скрипт `lint-k8s` не потрібен.
+
+### Винятки kubescape: `.kubescape-exceptions.json`
+
+Якщо в **корені проєкту** є файл **`.kubescape-exceptions.json`** — `lint-k8s` автоматично передає його в `kubescape scan` через **`--exceptions`** ([postureExceptionPolicy](https://github.com/kubescape/kubescape/blob/master/docs/exceptions.md)).
+
+Канонічний кейс — **C-0012** (`Applications credentials in configuration files`, High): control тригериться на **ім'я** env, що містить підрядок `secret`/`password`/`key`/`token`, а **не** на значення. Точкове виключення для ConfigMap із цим env: [.kubescape-exceptions.json.snippet.json](./templates/kubescape_exceptions/.kubescape-exceptions.json.snippet.json)
+
+Виключай контрольно, а не глобально (не додавай винятки без `attributes.name`/`labels`).
+
+### GitHub Actions: `lint-k8s.yml`
+
+Додай workflow **`.github/workflows/lint-k8s.yml`** (гілки **`dev`** і **`main`**, лише **`.yml`**). Після **`checkout`** використовуй локальний composite **`setup-bun-deps`**. Встановлення kubeconform / kubescape — окремі кроки. kustomize не встановлюємо окремо — `kubectl kustomize` вже на github-hosted runner'ах.
+
+```yaml title=".github/workflows/lint-k8s.yml"
+name: Lint K8s
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/k8s/**/*.yaml'
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  lint-k8s:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - name: Install kubeconform
+        run: |
+          curl -sSL "https://github.com/yannh/kubeconform/releases/download/v0.7.0/kubeconform-linux-amd64.tar.gz" | tar xz
+          sudo mv kubeconform /usr/local/bin/
+
+      - name: Install kubescape
+        run: |
+          curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh | /bin/bash
+          echo "$HOME/.kubescape/bin" >> $GITHUB_PATH
+
+      # kustomize не встановлюємо окремо — використовуємо вбудовану підкоманду `kubectl kustomize`
+      # (kubectl уже доступний на github-hosted runner'ах: https://github.com/actions/runner-images).
+
+      - name: Lint K8s
+        run: n-cursor lint k8s --read-only
+```

package/rules/k8s/js/multidoc_yaml.mdc

@@ -0,0 +1,5 @@
+## Багатодокументні YAML
+
+Одна схема на файл; скрипт звіряє **перший** документ (до наступного `---`). Інші `kind` у тому ж файлі — розділи файли або узгодь у рев'ю.
+
+**Розширення:** усі маніфести під **`k8s`**, включно з **`kustomization.yaml`**, — лише **`.yaml`** (розширення **`.yml`** не використовуй).

package/rules/k8s/js/network_policy.mdc

@@ -0,0 +1,136 @@
+## NetworkPolicy: канон egress/ingress
+
+Для **кожного** workload (**Deployment**, **StatefulSet**, **DaemonSet**, **Job**, **CronJob**) під `k8s` обов'язковий **NetworkPolicy** у **`base/networkpolicy.yaml`** поруч з workload-маніфестом (multi-doc через `---`, якщо workload-ів кілька). `metadata.name` NetworkPolicy **= `metadata.name`** workload; `spec.podSelector.matchLabels.app` **= мітка `app`** з `spec.selector.matchLabels` workload. Відсутні документи **`check k8s`** створює автоматично і додає `networkpolicy.yaml` у `base/kustomization.yaml` `resources:`.
+
+Два **повних** snippet-файли (JS-генератор/rego обирають один за `kind` workload-у через анотацію `metadata.annotations['nitra.dev/workload-kind']`):
+- [deployment.snippet.yaml](./policy/network_policy/template/deployment.snippet.yaml) — для `Deployment`/`Job`/`CronJob`/`DaemonSet`
+- [stateful-set.snippet.yaml](./policy/network_policy/template/stateful-set.snippet.yaml) — для `StatefulSet` (містить deployment-канон + intra-replica правила)
+
+### Канонічний `base/networkpolicy.yaml`
+
+`networking.k8s.io/v1`, `NetworkPolicy`, **без** `metadata.namespace` (namespace додає `base/kustomization.yaml`).
+
+**Ingress:** `from.podSelector: {}` (інші Pod у namespace).
+
+**Egress (усі workload-и):**
+- kube-dns через `kube-system` namespaceSelector (UDP/TCP 53);
+- link-local DNS `169.254.0.0/16` (UDP/TCP 53, GKE NodeLocal DNSCache);
+- **TCP 80 і 443** на `0.0.0.0/0` (HTTP/HTTPS назовні);
+- **in-cluster** — `to.namespaceSelector: {}` з **явним списком TCP-портів** (`80, 443, 5432, 3306, 1433, 6379, 8080, 4222, 4317, 4318`).
+
+**StatefulSet** додатково має egress/ingress `to/from.podSelector: {}` для intra-replica реплікації.
+
+Заборонено: `egress: [{}]`; `to.namespaceSelector: {}` без `ports:` (catch-all).
+
+```yaml title="k8s/base/networkpolicy.yaml"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/networkpolicy-networking-v1.json
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: backend-api
+  annotations:
+    nitra.dev/workload-kind: Deployment
+spec:
+  podSelector:
+    matchLabels:
+      app: backend-api
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - podSelector: {}
+  egress:
+    - to:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: kube-system
+          podSelector:
+            matchLabels:
+              k8s-app: kube-dns
+      ports:
+        - protocol: UDP
+          port: 53
+        - protocol: TCP
+          port: 53
+    - to:
+        - ipBlock:
+            cidr: 169.254.0.0/16
+      ports:
+        - protocol: UDP
+          port: 53
+        - protocol: TCP
+          port: 53
+    - to:
+        - ipBlock:
+            cidr: 0.0.0.0/0
+      ports:
+        - protocol: TCP
+          port: 80
+        - protocol: TCP
+          port: 443
+    - to:
+        - namespaceSelector: {}
+      ports:
+        - protocol: TCP
+          port: 80
+        - protocol: TCP
+          port: 443
+        - protocol: TCP
+          port: 5432
+        - protocol: TCP
+          port: 3306
+        - protocol: TCP
+          port: 1433
+        - protocol: TCP
+          port: 6379
+        - protocol: TCP
+          port: 8080
+        - protocol: TCP
+          port: 4222
+        - protocol: TCP
+          port: 4317
+        - protocol: TCP
+          port: 4318
+```
+
+### HTTPRoute → NetworkPolicy ingress (GCLB + Envoy)
+
+Якщо в каталозі workload є **`HTTPRoute`** (Gateway API) з **`backendRef`** на **`<workload>-hl`** Service, **`check k8s`** автоматично додає в NetworkPolicy цього workload **ingress-правило** з фіксованим набором CIDR-ів і **TCP-портами з `backendRefs[].port`** (дедуп, відсортовано за зростанням).
+
+Без цього правила трафік від **GKE Gateway** (Envoy proxy-only subnet, наприклад `10.10.0.0/23`) і **Google health checks** блокується базовим NetworkPolicy.
+
+CIDR-набір зафіксовано:
+- `35.191.0.0/16` — GCP HC global
+- `130.211.0.0/22` — GCP HC global (legacy)
+- `10.0.0.0/8` — широкий range, покриває proxy-only subnets усіх регіонів GKE
+
+```yaml title="k8s/base/networkpolicy.yaml — workload з HTTPRoute (з GCLB ingress)"
+# yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/networkpolicy-networking-v1.json
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: backend-api
+  annotations:
+    nitra.dev/workload-kind: Deployment
+spec:
+  podSelector:
+    matchLabels:
+      app: backend-api
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - podSelector: {}
+    - from: # auto-added by check k8s for HTTPRoute-paired workloads
+        - ipBlock: { cidr: 35.191.0.0/16 }
+        - ipBlock: { cidr: 130.211.0.0/22 }
+        - ipBlock: { cidr: 10.0.0.0/8 }
+      ports:
+        - { protocol: TCP, port: 8080 }
+  egress:
+    # ... (ідентично до базового прикладу вище)
+```
+
+Алгоритм: функція `collectHttpRouteIngressForWorkload` у **`rules/k8s/js/manifests.mjs`**.

package/rules/k8s/js/schema_modeline.mdc

@@ -0,0 +1,57 @@
+## Визначення схеми YAML (канон `yaml-language-server: $schema`)
+
+Для кожного файлу `*.yaml`, у шляху якого є сегмент директорії **`k8s`**, якщо існує **публічна** схема — **перший рядок** — коментар-директива для [YAML Language Server](https://github.com/redhat-developer/yaml-language-server) з URL за `https://`:
+
+```yaml
+# yaml-language-server: $schema=https://...
+```
+
+Далі — вміст маніфесту без зайвого порожнього рядка між коментарем і YAML.
+
+**Modeline — опційний:** якщо для конкретного поєднання `apiVersion`/`kind` **немає** надійної публічної схеми (yannh/datree/schemastore не покривають), залиш файл **без** рядка `# yaml-language-server: $schema=…`. **Заборонено** ставити `$schema=file:…` як заглушку.
+
+**Виняток — modeline заборонено:** `apiVersion: alb.yc.io/v1alpha1`, `kind: HttpBackendGroup` (Yandex ALB) — рядка **`# yaml-language-server: $schema=…`** у файлі **не** має бути. Перший рядок — одразу YAML (`apiVersion:` тощо). Перевірка — **`rules/k8s/fix.mjs`**.
+
+### Правила визначення URL схеми
+
+Орієнтир — **перший документ** (до наступного `---`).
+
+1. **Ім'я** `kustomization.yaml` → `https://json.schemastore.org/kustomization.json`.
+
+2. **`apiVersion: v1`** → yannh, PIN набору схем **`v1.33.9-standalone-strict`**, ref репозиторію для raw URL — **`master`**:
+   `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/<PIN>/<kind>-v1.json`
+   `<kind>`: літери в нижньому регістрі без роздільників між CamelCase (наприклад `Service` → `service`).
+
+   **`kind: Secret`** і **`type: kubernetes.io/basic-auth`** — той самий шаблон, **`secret-v1.json`**:
+
+   ```yaml
+   # yaml-language-server: $schema=https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/v1.33.9-standalone-strict/secret-v1.json
+   ```
+
+3. **`apiVersion: group/version`** і **group** у **`YANNH_GROUPS`** у скрипті → yannh:
+   `https://raw.githubusercontent.com/yannh/kubernetes-json-schema/master/<PIN>/<kind>-<group-частина>-<version>.json`
+   де **`<group-частина>`** — **перший сегмент** `group` до першої крапки: для груп без крапок збігається з усією group (`apps/v1` + `Deployment` → `deployment-apps-v1.json`); для `*.k8s.io` / `*.apiserver.k8s.io` — лише префікс до `.k8s.io` (`networking.k8s.io/v1` + `Ingress` → `ingress-networking-v1.json`; `networking.k8s.io/v1` + `NetworkPolicy` → `networkpolicy-networking-v1.json`; `rbac.authorization.k8s.io/v1` + `ClusterRole` → `clusterrole-rbac-v1.json`; `flowcontrol.apiserver.k8s.io/v1` + `FlowSchema` → `flowschema-flowcontrol-v1.json`). У yannh **немає** файлів з фрагментом `-k8s-io-` у назві.
+
+4. **Інакше** (CRD тощо) → [datreeio/CRDs-catalog](https://github.com/datreeio/CRDs-catalog). Типово для `$schema` у редакторі — **GitHub Pages**:
+   `https://datreeio.github.io/CRDs-catalog/<group>/<kind>_<version>.json`
+   (`<kind>` — лише літери та цифри в нижньому регістрі, без роздільників між CamelCase.)
+
+   **Виняток — `InfisicalSecret`:** `apiVersion: secrets.infisical.com/v1alpha1`, `kind: InfisicalSecret` — канонічний modeline через **raw** на гілці **`main`**:
+
+   ```yaml
+   # yaml-language-server: $schema=https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/secrets.infisical.com/infisicalsecret_v1alpha1.json
+   ```
+
+   **Приклад (Gateway API):** `apiVersion: gateway.networking.k8s.io/v1`, `kind: HTTPRoute`:
+
+   ```yaml
+   # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/gateway.networking.k8s.io/httproute_v1beta1.json
+   ```
+
+   **Приклад (GKE):** `apiVersion: networking.gke.io/v1`, `kind: HealthCheckPolicy`:
+
+   ```yaml
+   # yaml-language-server: $schema=https://datreeio.github.io/CRDs-catalog/networking.gke.io/healthcheckpolicy_v1.json
+   ```
+
+5. **Немає надійного публічного URL** — не вигадуй URL і **не** використовуй `$schema=file:…`. Залиш файл **без** рядка `# yaml-language-server: $schema=…` зовсім.

package/rules/k8s/js/service.mdc

@@ -0,0 +1,44 @@
+## Service: заборонені анотації GKE
+
+У **`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)
+
+Пара файлів для кластерного й 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**).
+
+**Точні умови та повідомлення `fail`** — верхній JSDoc **`npm/scripts/rules/k8s/fix.mjs`**.
+
+### Gateway API: не дублюй namespace у `backendRef`
+
+У маршрутах Gateway API (**HTTPRoute**, **GRPCRoute**, **TCPRoute**, **TLSRoute**, **UDPRoute**) у `spec.rules[*].backendRefs[*]` **не** додавай поле **`namespace`**, якщо його значення збігається з **`metadata.namespace`** самого маршруту. **`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); правило цього випадку не торкається.