@nitra/cursor 12.8.6 → 12.8.8

package/rules/ga/js/workflow_common.mdc

@@ -0,0 +1,108 @@
+## Універсальні правила для всіх workflow-файлів
+
+Перевіряє кожен `.github/workflows/*.yml` через Rego-пакет `ga.workflow_common`.
+
+### Блок `concurrency` — обов'язковий
+
+**Кожен** workflow у `.github/workflows/*.yml` **обов'язково** містить блок `concurrency` з фіксованим `group` та `cancel-in-progress: true`:
+
+```yaml
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+```
+
+Без винятків — у scheduled cleanup-воркфлоу, у `pull_request: types: [closed]`, у publish-воркфлоу теж. Це уникає паралельних запусків того самого workflow на тій самій ref і скасовує попередні в чергу нових.
+
+### Локальний composite `setup-bun-deps` — обов'язковий
+
+**ЗАБОРОНЕНО** дублювати кроки встановлення Bun та кешування безпосередньо у workflow файлах. Завжди використовуй локальний composite action.
+
+**Локальний composite** (`uses: ./.github/actions/setup-bun-deps` або `./npm/github-actions/setup-bun-deps`): **спочатку** обов'язковий крок **`actions/checkout@v6`** (`persist-credentials: false`), інакше runner не знайде `action.yml`. Сам composite: **`actions/setup-node@v6`** (**Node 24**), **Bun**, **`actions/cache@v5`**, **`bun install --frozen-lockfile`**.
+
+### Приклад (НЕПРАВИЛЬНО)
+
+```yaml
+    steps:
+      - uses: actions/checkout@v6
+      - uses: oven-sh/setup-bun@v2
+      - uses: actions/cache@v5
+        # ... багато рядків кешування ...
+      - run: bun install --frozen-lockfile
+```
+
+### Приклад (ПРАВИЛЬНО)
+
+```yaml
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup-bun-deps
+```
+
+### Крок `run:` — folded block `>-`
+
+**Кроки `run`:** не розбивай команду shell-продовженням через зворотний сліш у кінці рядка (`… \` у `run: |`). Замість багаторядкового буквального блока з `\\` оформ довгу одну shell-команду як **folded block** `>-` (рядки з'єднаються в один рядок із пробілами).
+
+**Читабельність `run: >-` з циклами/умовами:** оскільки `>-` **згортає рядки в один shell-рядок**, відступи потрібні **лише для читабельності** й не впливають на виконання. Але для конструкцій bash на кшталт `while …; do … done` та `if …; then … fi` **обов'язково**:
+
+- став явні роздільники команд **`;`** або **`&&`** там, де при згортанні рядків інакше "злипнуться" токени (`do`/`then`/`fi`/`done` з наступною командою);
+- тримай `do` і `then` в одному логічному рядку як `…; do` / `…; then`, щоб після згортання це гарантовано лишалось валідним bash;
+- додавай відступи всередині `do/then/else` блоків, навіть якщо це один рядок після згортання — так workflow лишається читабельним у diff.
+
+### Приклад (ПРАВИЛЬНО — читабельно, `run: >-`, з `while`/`if`)
+
+```yaml
+      - name: Apply changes
+        shell: bash
+        run: >-
+          echo "$FILES" |
+          while read -r FILE; do
+            [ -z "$FILE" ] && continue;
+            dirname "$FILE";
+          done |
+          sort -u |
+          while read -r DIR; do
+            (
+              if [ -f "$DIR/kustomization.yaml" ]; then
+                printf 'Applying %s\n' "$DIR" &&
+                cd "$DIR" &&
+                kubectl apply -k .;
+              else
+                echo "Skip $DIR - no kustomization.yaml";
+              fi
+            );
+          done
+```
+
+### Приклад run (НЕПРАВИЛЬНО — `\\` на кінцях)
+
+```yaml
+      - run: |
+          docker build \
+          --push \
+          --build-arg BRANCH=${{ github.ref_name }}
+```
+
+### Приклад run (ПРАВИЛЬНО — `>-`)
+
+```yaml
+      - run: >-
+          docker build
+          --push
+          --build-arg BRANCH=${{ github.ref_name }}
+```
+
+### Мінімальні версії marketplace actions
+
+Канон: [uses-min-versions.snippet.json](./policy/workflow_common/template/uses-min-versions.snippet.json)
+
+- `actions/checkout` — **не нижче major `v6`** (`@v6`, `@v6.0.2` тощо дозволені; `@v5` — ні);
+- `Infisical/secrets-action` — **не нижче `v1.0.16`** (Node 24; нижчі теги лишаються на Node 20, deprecated з червня 2026).
+
+SHA-pin (40 hex) semver-політику не застосовує. Для checkout рекомендується **`v6.0.2+`** (Node 24 у action), але мінімум політики — лише major **6**.
+
+### Заборона `depcheck` у workflow
+
+**`depcheck`:** не використовувати у `.github/workflows/*.yml` — мігровано на `knip` (div. `js.mdc`). Перевірка невикористаних залежностей виконується разом з рештою лінтерів у `lint-js`, окремий крок `npx depcheck` у workflow не потрібен і блокується полісі `ga.workflow_common`.

package/rules/ga/js/workflows.mdc

@@ -0,0 +1,32 @@
+## Структура workflow-файлів та обов'язкові workflows
+
+У `.github/workflows/` лише **`.yml`** (не `.yaml`). Обов'язкові файли:
+
+- **`clean-ga-workflows.yml`**
+- **`clean-merged-branch.yml`**
+- **`lint-ga.yml`**
+- **`git-ai.yml`**
+
+Якщо є **`apply-k8s.yml`** — тригер `on.push.paths` має містити `**/k8s/**/*.yaml`.
+Якщо є **`apply-nats-consumer.yml`** — тригер `on.push.paths` має містити `**/consumer.yaml`.
+
+## Перевірка glob-патернів `on.push.paths`
+
+Кожен позитивний glob у `on.push.paths` / `on.pull_request.paths` (крім `!`-негацій та `*`-extension-фільтрів) має матчитися хоча б на один tracked файл у репозиторії (`git ls-files`). Шаблони на кшталт `*.vue` чи `{*.ts,*.js}` пропускаються — вони можуть бути заготовками для майбутніх файлів. Конкретні директорії (`some-dir/**`) — перевіряються.
+
+## Заборона MegaLinter
+
+**MegaLinter** не використовувати. Треба видалити:
+
+- workflow-файли з `oxsecurity/megalinter-action` або `megalinter/megalinter`
+- конфіги: `.mega-linter.yml`, `.megalinter.yaml`, `.mega-linter.yaml`
+- будь-які залежності та згадки в CI / pre-commit / документації
+
+## Shellcheck у PATH
+
+`actionlint` (через `bunx github-actionlint`) запускає shell-перевірки в кроках `run:` лише коли `shellcheck` доступний у PATH — інакше мовчки пропускає SC-правила. Локальний `bun lint-ga` лишається зеленим, а CI на `ubuntu-latest` (де shellcheck передвстановлений) падає.
+
+Встанови `shellcheck`:
+- macOS: `brew install shellcheck`
+- Debian/Ubuntu: `sudo apt-get install -y shellcheck`
+- Arch: `sudo pacman -S shellcheck`

package/rules/ga/js/zizmor.mdc

@@ -0,0 +1,7 @@
+## `.github/zizmor.yml` — конфігурація zizmor
+
+Для [unpinned-uses](https://docs.zizmor.sh/audits/#unpinned-uses) — політика **`ref-pin`**, якщо в `uses:` семантичні теги. За потреби вимкни [template-injection](https://docs.zizmor.sh/audits/#template-injection).
+
+- Канон `.github/zizmor.yml`: [zizmor.yml.snippet.yml](./policy/zizmor_yml/template/zizmor.yml.snippet.yml)
+
+Rego-пакет `ga.zizmor_yml`: перевіряє `rules.unpinned-uses.config.policies["*"]` відповідно до значення з template.

package/rules/ga/main.mdc

@@ -5,137 +5,34 @@ globs: ".github/workflows/*.yml"
 alwaysApply: false
 ---
 
-У `.github/workflows/` лише **`.yml`**. Мають бути **`clean-ga-workflows.yml`**, **`clean-merged-branch.yml`**, **`lint-ga.yml`**, **`git-ai.yml`**. Якщо є **`apply-k8s.yml`** / **`apply-nats-consumer.yml`** — paths у тригері як у фрагментах.
+Правило **ga** перевіряє структуру `.github/workflows/`, наявність обов'язкових workflow-файлів і їх відповідність канонам, а також налаштування VS Code та zizmor для роботи з GitHub Actions.
 
-**Кожен** workflow у `.github/workflows/*.yml` **обов'язково** містить блок `concurrency` з фіксованим `group` та `cancel-in-progress: true`:
+[ga-workflows](./js/workflows.mdc)
 
-```yaml
-concurrency:
-  group: ${{ github.ref }}-${{ github.workflow }}
-  cancel-in-progress: true
-```
+[ga-workflow_common](./js/workflow_common.mdc)
 
-Без винятків — у scheduled cleanup-воркфлоу, у `pull_request: types: [closed]`, у publish-воркфлоу теж. Це уникає паралельних запусків того самого workflow на тій самій ref і скасовує попередні в чергу нових.
+[ga-required_workflows](./js/required_workflows.mdc)
 
-Повинен бути файл `.github/workflows/clean-ga-workflows.yml`:
+[ga-vscode](./js/vscode.mdc)
 
-- Канон: [clean-ga-workflows.yml.snippet.yml](./policy/clean_ga_workflows/template/clean-ga-workflows.yml.snippet.yml)
+[ga-zizmor](./js/zizmor.mdc)
 
-Повинен бути файл `.github/workflows/clean-merged-branch.yml`:
+[ga-lint_toolchain](./js/lint_toolchain.mdc)
 
-- Канон: [clean-merged-branch.yml.snippet.yml](./policy/clean_merged_branch/template/clean-merged-branch.yml.snippet.yml)
+## Швидкий gate через conftest
 
-Інші гілки в `ignore_branches` — допустимо.
+[ga-workflow_common](./policy/workflow_common/workflow_common.mdc)
 
-Повинен бути файл `.github/workflows/lint-ga.yml`:
+[ga-clean_ga_workflows](./policy/clean_ga_workflows/clean_ga_workflows.mdc)
 
-- Канон: [lint-ga.yml.snippet.yml](./policy/lint_ga/template/lint-ga.yml.snippet.yml)
+[ga-clean_merged_branch](./policy/clean_merged_branch/clean_merged_branch.mdc)
 
-Повинен бути файл `.github/workflows/git-ai.yml`:
+[ga-lint_ga](./policy/lint_ga/lint_ga.mdc)
 
-- Канон: [git-ai.yml.snippet.yml](./policy/git_ai/template/git-ai.yml.snippet.yml)
+[ga-git_ai](./policy/git_ai/git_ai.mdc)
 
-**Мінімальні версії marketplace actions** у `uses:` (перевіряє `ga.workflow_common`):
+[ga-vscode_extensions](./policy/vscode_extensions/vscode_extensions.mdc)
 
-- `actions/checkout` — **не нижче major `v6`** (`@v6`, `@v6.0.2` тощо дозволені; `@v5` — ні);
-- `Infisical/secrets-action` — **не нижче `v1.0.16`** (Node 24; нижчі теги лишаються на Node 20, deprecated з червня 2026).
+[ga-vscode_settings](./policy/vscode_settings/vscode_settings.mdc)
 
-Канон: [uses-min-versions.snippet.json](./policy/workflow_common/template/uses-min-versions.snippet.json). SHA-pin (40 hex) semver-політику не застосовує. Для checkout рекомендується **`v6.0.2+`** (Node 24 у action), але мінімум політики — лише major **6**.
-
-**Локальний composite** (`uses: ./.github/actions/setup-bun-deps` або `./npm/github-actions/setup-bun-deps`): **спочатку** обов’язковий крок **`actions/checkout@v6`** (`persist-credentials: false`), інакше runner не знайде `action.yml`. Сам composite: **`actions/setup-node@v6`** (**Node 24**), **Bun**, **`actions/cache@v5`**, **`bun install --frozen-lockfile`**.
-
-**ЗАБОРОНЕНО** дублювати кроки встановлення Bun та кешування безпосередньо у workflow файлах. Завжди використовуй локальний composite action.
-
-**Кроки `run`:** не розбивай команду shell-продовженням через зворотний сліш у кінці рядка (`… \` у `run: |`). Замість багаторядкового буквального блока з `\\` оформ довгу одну shell-команду як **folded block** `>-` (рядки з’єднаються в один рядок із пробілами).
-
-**Читабельність `run: >-` з циклам/умовами:** оскільки `>-` **згортає рядки в один shell-рядок**, відступи потрібні **лише для читабельності** й не впливають на виконання. Але для конструкцій bash на кшталт `while …; do … done` та `if …; then … fi` **обовʼязково**:
-
-- став явні роздільники команд **`;`** або **`&&`** там, де при згортанні рядків інакше “злипнуться” токени (`do`/`then`/`fi`/`done` з наступною командою);
-- тримай `do` і `then` в одному логічному рядку як `…; do` / `…; then`, щоб після згортання це гарантовано лишалось валідним bash;
-- додавай відступи всередині `do/then/else` блоків, навіть якщо це один рядок після згортання — так workflow лишається читабельним у diff.
-
-### Приклад (ПРАВИЛЬНО — читабельно, `run: >-`, з `while`/`if`)
-
-```yaml
-      - name: Apply changes
-        shell: bash
-        run: >-
-          echo "$FILES" |
-          while read -r FILE; do
-            [ -z "$FILE" ] && continue;
-            dirname "$FILE";
-          done |
-          sort -u |
-          while read -r DIR; do
-            (
-              if [ -f "$DIR/kustomization.yaml" ]; then
-                printf 'Applying %s\n' "$DIR" &&
-                cd "$DIR" &&
-                kubectl apply -k .;
-              else
-                echo "Skip $DIR - no kustomization.yaml";
-              fi
-            );
-          done
-```
-
-### Приклад run (НЕПРАВИЛЬНО — `\\` на кінцях)
-
-```yaml
-      - run: |
-          docker build \
-          --push \
-          --build-arg BRANCH=${{ github.ref_name }}
-```
-
-### Приклад run (ПРАВИЛЬНО — `>-`)
-
-```yaml
-      - run: >-
-          docker build
-          --push
-          --build-arg BRANCH=${{ github.ref_name }}
-```
-
-### Приклад (НЕПРАВИЛЬНО)
-
-```yaml
-    steps:
-      - uses: actions/checkout@v6
-      - uses: oven-sh/setup-bun@v2
-      - uses: actions/cache@v5
-        # ... багато рядків кешування ...
-      - run: bun install --frozen-lockfile
-```
-
-### Приклад (ПРАВИЛЬНО)
-
-```yaml
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          persist-credentials: false
-      - uses: ./.github/actions/setup-bun-deps
-```
-
-**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Запуск — через **`n-cursor lint ga`** (CI — `--read-only`; бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`. Окремого `package.json`-скрипта немає.
-
-> Виклик через bin-ім’я `n-cursor` (а **не** `npx @nitra/cursor`): `bun x`/`npx` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання, тому в CI-кроці `run:` використовуй саме `n-cursor lint <rule>`.
-
-CLI робить preflight на `shellcheck` і `uv` (`uvx`) у `PATH`, потім запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
-
-**`.github/zizmor.yml`:** для [unpinned-uses](https://docs.zizmor.sh/audits/#unpinned-uses) — політика **`ref-pin`**, якщо в `uses:` семантичні теги. За потреби вимкни [template-injection](https://docs.zizmor.sh/audits/#template-injection):
-
-- Канон `.github/zizmor.yml`: [zizmor.yml.snippet.yml](./policy/zizmor_yml/template/zizmor.yml.snippet.yml)
-
-**`.vscode/extensions.json`** має рекомендувати `github.vscode-github-actions`:
-
-- Канон: [extensions.json.snippet.json](./policy/vscode_extensions/template/extensions.json.snippet.json)
-
-**`.vscode/settings.json`** для мови `github-actions-workflow` має `editor.defaultFormatter = "oxc.oxc-vscode"`:
-
-- Канон: [settings.json.snippet.json](./policy/vscode_settings/template/settings.json.snippet.json)
-
-**MegaLinter:** не використовувати; прибрати workflow, конфіги (`.mega-linter.yml`, `.megalinter.yaml`, `.mega-linter.yaml`), залежності та згадки в CI / pre-commit / документації.
-
-**`depcheck`:** не використовувати у `.github/workflows/*.yml` — мігровано на `knip` (див. `js.mdc`). Перевірка невикористаних залежностей виконується разом з рештою лінтерів у `lint-js`, окремий крок `npx depcheck` у workflow не потрібен і блокується полісі `ga.workflow_common`.
+[ga-zizmor_yml](./policy/zizmor_yml/zizmor_yml.mdc)

package/rules/ga/policy/clean_ga_workflows/clean_ga_workflows.mdc

@@ -0,0 +1,18 @@
+## Структура `clean-ga-workflows.yml` — видалення завершених workflow runs
+
+Rego-пакет: `ga.clean_ga_workflows`
+
+**Цільовий файл:** `.github/workflows/clean-ga-workflows.yml`
+
+### Що перевіряється
+
+- `name` — точна відповідність значенню з template
+- `on.schedule[].cron` — має містити cron із template (`0 1 16 * *`)
+- `on.workflow_dispatch` — має бути об'єктом `{}`
+- `jobs.cleanup_old_workflows` — job має існувати
+- `jobs.cleanup_old_workflows.runs-on` — відповідно до template (`ubuntu-latest`)
+- `jobs.cleanup_old_workflows.permissions` — `actions: write`, `contents: read`
+- `steps[0].name` і `steps[0].uses` — відповідно до template (`dmvict/clean-workflow-runs@v1`)
+- `steps[0].with` — `token`, `save_period`, `save_min_runs_number` як у template
+
+Канон: [clean-ga-workflows.yml.snippet.yml](./template/clean-ga-workflows.yml.snippet.yml)

package/rules/ga/policy/clean_merged_branch/clean_merged_branch.mdc

@@ -0,0 +1,22 @@
+## Структура `clean-merged-branch.yml` — видалення злитих гілок
+
+Rego-пакет: `ga.clean_merged_branch`
+
+**Цільовий файл:** `.github/workflows/clean-merged-branch.yml`
+
+### Що перевіряється
+
+- `name` — точна відповідність значенню з template
+- `on.schedule[].cron` — має містити cron із template (`0 1 15 * *`)
+- `on.workflow_dispatch` — має бути об'єктом `{}`
+- `jobs.cleanup_old_branches` — job має існувати
+- `jobs.cleanup_old_branches.permissions` — кожне поле із template (`contents: write`, `pull-requests: read`)
+- `steps` — має бути рівно 2 кроки
+- `steps[0].id` — `delete_stuff`; `steps[0].uses` — `phpdocker-io/github-actions-delete-abandoned-branches@v2.0.3`
+- `steps[0].with.github_token`, `last_commit_age_days` — за template
+- `steps[0].with.ignore_branches` — має містити всі гілки з template (`main,dev`)
+- `steps[0].with.dry_run` — `no` (нормалізується: YAML 1.1 `no` → boolean `false` у conftest)
+- `steps[1].name` — за template; `steps[1].env.DELETED_BRANCHES` — за template
+- `steps[1].run` — містить `Deleted branches:` та `${DELETED_BRANCHES}`
+
+Канон: [clean-merged-branch.yml.snippet.yml](./template/clean-merged-branch.yml.snippet.yml)

package/rules/ga/policy/git_ai/git_ai.mdc

@@ -0,0 +1,19 @@
+## Структура `git-ai.yml` — автоматичний запуск git-ai після мержу PR
+
+Rego-пакет: `ga.git_ai`
+
+**Цільовий файл:** `.github/workflows/git-ai.yml`
+
+### Що перевіряється
+
+- `name` — точна відповідність значенню з template (`Git AI`)
+- `on.pull_request.types` — має містити `closed`
+- `jobs.git-ai` — job має існувати
+- `jobs.git-ai.if` — містить `github.event.pull_request.merged == true`
+- `jobs.git-ai.permissions.contents` — за template (`write`)
+- `steps[*].run` (сукупно) — містить substring `https://usegitai.com/install.sh` (інсталяція)
+- `steps[*].run` (сукупно) — містить substring `git-ai ci github run` (запуск)
+
+Substring-перевірки замість exact-match через крихкість multi-line `run:` блоків.
+
+Канон: [git-ai.yml.snippet.yml](./template/git-ai.yml.snippet.yml)

package/rules/ga/policy/lint_ga/lint_ga.mdc

@@ -0,0 +1,21 @@
+## Структура `lint-ga.yml` — CI-лінт GitHub Actions файлів
+
+Rego-пакет: `ga.lint_ga`
+
+**Цільовий файл:** `.github/workflows/lint-ga.yml`
+
+### Що перевіряється
+
+- `name` — точна відповідність значенню з template (`Lint GA`)
+- `on.push.branches` — superset: містить `dev` і `main`
+- `on.pull_request.branches` — superset: містить `dev` і `main`
+- `on.push.paths` — superset: містить `.github/actions/**` і `.github/workflows/**`
+- `jobs.lint-ga` — job має існувати
+- `jobs.lint-ga.runs-on` — за template (`ubuntu-latest`)
+- `jobs.lint-ga.permissions.contents` — `read`
+- `jobs.lint-ga.steps` — не порожній
+- `steps[*].uses` — кожен `uses:` з template має бути присутнім у кроках
+- `steps[*].run` (сукупно) — містить `open-policy-agent/conftest` (Install conftest)
+- `steps[*].run` (сукупно) — містить `n-cursor lint ga --read-only`
+
+Канон: [lint-ga.yml.snippet.yml](./template/lint-ga.yml.snippet.yml)

package/rules/ga/policy/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,9 @@
+## `.vscode/extensions.json` — розширення для GitHub Actions
+
+Rego-пакет: `ga.vscode_extensions`
+
+**Цільовий файл:** `.vscode/extensions.json`
+
+Кожне розширення з template має бути присутнє у `recommendations`. Додаткові розширення від інших правил — допустимі (subset-перевірка).
+
+Канон: [extensions.json.snippet.json](./template/extensions.json.snippet.json)

package/rules/ga/policy/vscode_settings/vscode_settings.mdc

@@ -0,0 +1,9 @@
+## `.vscode/settings.json` — налаштування форматування GitHub Actions workflow
+
+Rego-пакет: `ga.vscode_settings`
+
+**Цільовий файл:** `.vscode/settings.json`
+
+Перевіряє 2-рівневу структуру: для кожного `<block-key>` з template кожен `<leaf-key>` у відповідному блоці input має точно відповідати очікуваному значенню. Ключі можуть містити дужки та крапки (VS Code-конвенція, наприклад `[github-actions-workflow]`).
+
+Канон: [settings.json.snippet.json](./template/settings.json.snippet.json)

package/rules/ga/policy/workflow_common/workflow_common.mdc

@@ -0,0 +1,18 @@
+## Універсальні Rego-перевірки для всіх workflow-файлів
+
+Rego-пакет: `ga.workflow_common`
+
+**Цільові файли:** `.github/workflows/*.yml` (кожен файл окремо)
+
+### Що перевіряється
+
+- **concurrency** — обов'язкова наявність блоку; `group` = `${{ github.ref }}-${{ github.workflow }}`; `cancel-in-progress: true`
+- **Заборонені кроки** — `oven-sh/setup-bun`, `actions/cache`, `bun install` у будь-якому `uses:`/`run:` (мають бути інкапсульовані у composite `setup-bun-deps`)
+- **Порядок кроків** — якщо є `setup-bun-deps`, перед ним обов'язковий `actions/checkout@`
+- **Shell-продовження** — `\` перед переносом рядка у `run:` заборонено; треба `run: >-`
+- **Заборонені команди** — `depcheck` у `run:` (мігровано на `knip`)
+- **Мінімальні версії** — `uses:` з marketplace-actions перевіряються за канонічним JSON
+
+Канон мінімальних версій: [uses-min-versions.snippet.json](./template/uses-min-versions.snippet.json)
+
+Детальна документація поведінки — у [ga-workflow_common](../../js/workflow_common.mdc).

package/rules/ga/policy/zizmor_yml/zizmor_yml.mdc

@@ -0,0 +1,9 @@
+## `.github/zizmor.yml` — конфігурація zizmor для unpinned-uses
+
+Rego-пакет: `ga.zizmor_yml`
+
+**Цільовий файл:** `.github/zizmor.yml`
+
+Перевіряє `rules.unpinned-uses.config.policies["*"]` — значення має точно відповідати template (`ref-pin`). Всі вкладені об'єкти читаються через `object.get` із дефолтами, тож відсутні ключі коректно детектуються як порушення.
+
+Канон: [zizmor.yml.snippet.yml](./template/zizmor.yml.snippet.yml)

package/rules/graphql/js/tooling.mdc

@@ -0,0 +1,13 @@
+## Умовна вимога `.graphqlrc.yml`
+
+Якщо у `.vue` або в JavaScript / TypeScript джерелах (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx` тощо) зустрічається **tagged template literal** з тегом **`gql`** (типово `gql\`query …\`` для GraphQL-запиту), у **корені репозиторію** має бути файл **`.graphqlrc.yml`** ([GraphQL Config](https://the-guild.dev/graphql/config/docs)).
+
+Перевірка є **умовною**: якщо жодного `gql\`…\`` у дереві не знайдено — `.graphqlrc.yml` не вимагається.
+
+Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
+
+```yaml title=".graphqlrc.yml"
+schema: node_modules/@nitra/efes-shared/schema/maya.graphql
+documents:
+  - '**/*.{vue,js,ts,tsx}'
+```

package/rules/graphql/js/vscode_extensions.mdc

@@ -0,0 +1,13 @@
+## Розширення VS Code для GraphQL
+
+Якщо у проєкті є `gql\`…\`` tagged template literals, у **`.vscode/extensions.json`** в масиві **`recommendations`** має бути запис **`graphql.vscode-graphql`**.
+
+Канон задає мінімум — інші записи (від markdownlint, oxc тощо) дозволені. Перевірка виконується Rego-пакетом `graphql.vscode_extensions` через `conftest` і запускається лише після того, як JS-сканер виявив `gql` у дереві.
+
+Додай `graphql.vscode-graphql` до наявного списку `recommendations` (не замінюй інші записи):
+
+```json title=".vscode/extensions.json"
+{
+  "recommendations": ["graphql.vscode-graphql"]
+}
+```

package/rules/graphql/main.mdc

@@ -5,27 +5,10 @@ globs: "**/*.{vue,js,mjs,cjs,ts,tsx,jsx}"
 alwaysApply: false
 ---
 
-Якщо в **`.vue`** або в **JavaScript / TypeScript** джерелах (`.js`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.jsx` тощо) зустрічається **tagged template literal** з тегом **`gql`** (типово `gql\`query …\`` для GraphQL-запиту), у **корені репозиторію** мають бути:
+Якщо у `.vue` або JavaScript / TypeScript джерелах зустрічається **tagged template literal** з тегом **`gql`**, у корені репозиторію мають бути `.graphqlrc.yml` та запис `graphql.vscode-graphql` у `.vscode/extensions.json`.
 
-- файл **`.graphqlrc.yml`** ([GraphQL Config](https://the-guild.dev/graphql/config/docs));
-- у **`.vscode/extensions.json`** в масиві **`recommendations`** — запис **`graphql.vscode-graphql`**.
+[graphql-tooling](./js/tooling.mdc)
 
-## `.graphqlrc.yml`
+[graphql-vscode-extensions](./js/vscode_extensions.mdc)
 
-Підстав свої шляхи до схеми та до файлів з операціями; приклад орієнтиру:
-
-```yaml title=".graphqlrc.yml"
-schema: node_modules/@nitra/efes-shared/schema/maya.graphql
-documents:
-  - '**/*.{vue,js,ts,tsx}'
-```
-
-## `.vscode/extensions.json`
-
-Додай **`graphql.vscode-graphql`** до наявного списку **`recommendations`** (не замінюй інші записи):
-
-```json title=".vscode/extensions.json"
-{
-  "recommendations": ["graphql.vscode-graphql"]
-}
-```
+[graphql-vscode-extensions-policy](./policy/vscode_extensions/vscode_extensions.mdc)

package/rules/graphql/policy/vscode_extensions/vscode_extensions.mdc

@@ -0,0 +1,9 @@
+## Rego-перевірка наявності graphql.vscode-graphql у recommendations
+
+Rego-пакет: `graphql.vscode_extensions`
+
+Цільовий файл: `.vscode/extensions.json` (передається явно через `runConftestBatch` — без `target.json`, тому не auto-discoverable).
+
+Перевіряє: поле `recommendations` містить рядок `"graphql.vscode-graphql"`. Порожній масив або відсутнє поле — deny. Додаткові записи дозволені.
+
+Запускається умовно — лише якщо JS-сканер виявив `gql\`…\`` у джерелах проєкту.

package/rules/hasura/js/internal_urls.mdc

@@ -0,0 +1,27 @@
+## Внутрішній кластерний URL для HASURA_GRAPHQL_ENDPOINT
+
+У `*.env` для атрибута `HASURA_GRAPHQL_ENDPOINT` підключення має бути **усередині кластера**, а не через публічний домен — інакше CI кладе метадані через зовнішній бекенд і ламає перевипуск/міграції.
+
+Правило застосовується лише до проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
+
+Файл `.env` (без імені) — виключення з цього правила, його змінювати не потрібно.
+
+Приклад **неправильного** значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=https://vybeerai.com.ua/contract/ql
+```
+
+Правильне значення:
+
+```env
+HASURA_GRAPHQL_ENDPOINT=http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
+```
+
+де `contract-h-hl` — це `metadata.name` headless Service з `hasura/k8s/base/svc-hl.yaml` (пара з clusterIP `contract-h` у `svc.yaml`, якщо є; узгоджено з k8s: суфікс `-hl` на базі `-h`), а `ua-contract` — `metadata.name` namespace з `hasura/k8s/base/namespace.yaml`.
+
+Формат URL: `http://<service>.<namespace>.svc.<cluster>.internal:<port>`
+
+- `http://` обов'язковий (TLS усередині кластера зайвий)
+- DNS-суфікс — `<cluster>.internal` (GKE/GCP)
+- Сервіс і namespace звіряються з `hasura/k8s/base/svc-hl.yaml` та `hasura/k8s/base/namespace.yaml`

package/rules/hasura/js/migrations.mdc

@@ -0,0 +1,13 @@
+## Міграції: лише `up.sql`, без `down.sql`
+
+При створенні будь-якої нової директорії міграції у `hasura/migrations/` **не створювати файл `down.sql`**.
+У директорії міграції має бути **тільки `up.sql`**.
+
+Приклад коректної структури:
+
+```
+hasura/migrations/default/1781247030100_add_foo/
+└── up.sql   ✓
+```
+
+Файл `down.sql` у цьому проєкті **не використовується** і не повинен з'являтися.

package/rules/hasura/js/svc_hl.mdc

@@ -0,0 +1,17 @@
+## Іменування headless та clusterIP Service у hasura/k8s/base
+
+Hasura-конвенція іменування Service у `hasura/k8s/base/svc.yaml` та `svc-hl.yaml`:
+
+- **clusterIP Service** (`svc.yaml`) — базовий сегмент закінчується на **`-h`** (наприклад, `contract-h`)
+- **Headless Service** (`svc-hl.yaml`) — закінчується на **`-h-hl`** (наприклад, `contract-h-hl`)
+
+Пара: `contract-h` (clusterIP) + `contract-h-hl` (headless) — обидва імені мають бути узгоджені між собою та з `HASURA_GRAPHQL_ENDPOINT` у `*.env`.
+
+Перевірка виконується Rego-полісі `hasura.svc_hl` (package `hasura.svc_hl`):
+
+```
+conftest test hasura/k8s/base/svc-hl.yaml -p npm/rules/hasura/policy/svc_hl \
+  --namespace hasura.svc_hl
+```
+
+Cross-file перевірку (узгодженість `HASURA_GRAPHQL_ENDPOINT` ↔ YAML) виконує `js/internal_urls.mjs`.

package/rules/hasura/main.mdc

@@ -5,38 +5,14 @@ globs: "**/hasura/**,**/*.env"
 alwaysApply: false
 ---
 
-## Підключення для оновлення метаданих у CI (Nitra та Abinbevefes)
+Правило охоплює: коректність підключення Hasura у CI-середовищі (внутрішній URL кластера), конвенцію іменування k8s-сервісів та структуру директорій міграцій.
 
-У `*.env` для атрибута `HASURA_GRAPHQL_ENDPOINT` підключення має бути **усередині кластера**, а не через публічний домен — інакше CI кладе метадані через зовнішній бекенд і ламає перевипуск/міграції.
+[hasura-internal_urls](./js/internal_urls.mdc)
 
-Приклад **неправильного** значення:
+[hasura-svc_hl](./js/svc_hl.mdc)
 
-```env
-HASURA_GRAPHQL_ENDPOINT=https://vybeerai.com.ua/contract/ql
-```
+[hasura-migrations](./js/migrations.mdc)
 
-Правильне значення:
+## Швидкий gate через conftest
 
-```env
-HASURA_GRAPHQL_ENDPOINT=http://contract-h-hl.ua-contract.svc.abie-ua.internal:8080
-```
-
-де `contract-h-hl` — це `metadata.name` headless Service з `hasura/k8s/base/svc-hl.yaml` (пара з clusterIP `contract-h` у `svc.yaml`, якщо є; узгоджено з k8s: суфікс `-hl` на базі `-h`), а `ua-contract` — `metadata.name` namespace з `hasura/k8s/base/namespace.yaml`.
-
-Правило застосовується для проєктів **nitra** (у кореневому `package.json` `"repository": "https://github.com/nitra/*"`) і **abie** (`"repository": "https://github.com/abinbevefes/*"`); для інших репозиторіїв перевірка пропускається.
-
-Файл .env це (без імені) це виключення з цього правила, його змінювати не потрібно
-
-## Міграції: лише `up.sql`, без `down.sql`
-
-При створенні будь-якої нової директорії міграції у `hasura/migrations/` **не створювати файл `down.sql`**.
-У директорії міграції має бути **тільки `up.sql`**.
-
-Приклад коректної структури:
-
-```
-hasura/migrations/default/1781247030100_add_foo/
-└── up.sql   ✓
-```
-
-Файл `down.sql` у цьому проєкті **не використовується** і не повинен з'являтися.
+[hasura-svc_hl](./policy/svc_hl/svc_hl.mdc)