@nitra/cursor 3.4.1 → 3.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.6.0] - 2026-06-01
+
+### Added
+
+- flow: команда gate — структурований вердикт релізної готовності (PASS/CONCERNS/FAIL + score + причини, синтез verify-гейтів і review-findings); release м'яко попереджає на FAIL
+
+## [3.5.0] - 2026-06-01
+
+### Added
+
+- python: нове правило (uv-only, без Poetry) — автоактивація за pyproject.toml, заборона [tool.poetry]/poetry.lock, PEP 621 [project], lint-python (uv lock --check + uv sync --frozen + опц. ruff auto-fix: check --fix & format, mypy), CI workflow з astral-sh/setup-uv
+
 ## [3.4.1] - 2026-06-01
 
 ### Fixed

package/package.json

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

package/rules/flow/flow.mdc

@@ -79,7 +79,17 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
 7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.
 
-8. **Фініш** — лише після зеленого `verify`:
+8. **Gate (вердикт готовності)** — перед фінішем:
+
+   ```
+   npx @nitra/cursor flow gate
+   ```
+
+   Синтезує verify-гейти і review-findings у `PASS / CONCERNS / FAIL` + score +
+   причини (пише у `.flow.json`). `FAIL` (провалений gate або high-severity
+   finding) → код 1; `release` на FAIL лише попередить (рішення за тобою).
+
+9. **Фініш** — після зеленого `verify` і бажано `gate` ≠ FAIL:
 
    ```
    npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"

package/rules/python/fix.mjs

@@ -0,0 +1,19 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
+  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
+  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
+  process.exit(await runRuleCli(import.meta.dirname))
+}

package/rules/python/js/tooling.mjs

@@ -0,0 +1,68 @@
+/**
+ * Перевіряє FS-вимоги правила python.mdc для Python-проєктів на uv.
+ *
+ * **Що тут лишилося** (FS-existence — не покривається conftest):
+ *  - наявність `pyproject.toml` у корені (тригер правила);
+ *  - наявність `uv.lock` поруч (uv-проєкт коммітить lock-файл);
+ *  - наявність кореневого `package.json` (для `bun run lint-python`);
+ *  - наявність `.github/workflows/lint-python.yml`;
+ *  - заборона Poetry-артефактів `poetry.lock` / `poetry.toml` (міграція на uv).
+ *
+ * **Що покрила Rego** (`npx \@nitra/cursor fix python`):
+ *  - `python/pyproject_toml/` — заборона `[tool.poetry]` + вимога PEP 621 `[project].name/version`;
+ *  - `python/package_json/` — наявність скрипта `lint-python` у `package.json`;
+ *  - `python/lint_python_yml/` — `uses`/`run`-кроки канонічного workflow.
+ *
+ * `.venv/` навмисно НЕ перевіряється: uv теж створює `.venv`, тож його наявність
+ * не є ознакою Poetry й давала б хибні спрацювання.
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+
+/**
+ * Перевіряє відповідність проєкту правилам python.mdc.
+ * @param {string} [cwd] корінь репозиторію (`process.cwd()` у звичайному прогоні)
+ * @returns {number} 0 — все OK, 1 — є проблеми
+ */
+export function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  if (!existsSync(join(cwd, 'pyproject.toml'))) {
+    pass('pyproject.toml не знайдено в корені — правило python не застосовне')
+    return reporter.getExitCode()
+  }
+  pass('pyproject.toml існує — застосовую python.mdc')
+
+  if (existsSync(join(cwd, 'uv.lock'))) {
+    pass('uv.lock є')
+  } else {
+    fail('uv.lock не знайдено — згенеруй `uv lock` (python.mdc, без Poetry)')
+  }
+
+  // Poetry-артефакти заборонені: uv є єдиним пакет-менеджером (python.mdc).
+  for (const poetryFile of ['poetry.lock', 'poetry.toml']) {
+    if (existsSync(join(cwd, poetryFile))) {
+      fail(`${poetryFile} знайдено — прибери Poetry, мігруй на uv (python.mdc)`)
+    } else {
+      pass(`${poetryFile} відсутній`)
+    }
+  }
+
+  if (existsSync(join(cwd, 'package.json'))) {
+    pass('package.json є (наявність lint-python перевіряє fix → python.package_json)')
+  } else {
+    fail('package.json не знайдено в корені — додай для `bun run lint-python` (python.mdc)')
+  }
+
+  const wfPath = '.github/workflows/lint-python.yml'
+  if (existsSync(join(cwd, wfPath))) {
+    pass(`${wfPath} є (структуру перевіряє fix → python.lint_python_yml)`)
+  } else {
+    fail(`${wfPath} не існує — створи згідно python.mdc`)
+  }
+
+  return reporter.getExitCode()
+}

package/rules/python/lint/lint.mjs

@@ -0,0 +1,116 @@
+/**
+ * Запуск `lint-python` за правилом python.mdc на базі [uv](https://docs.astral.sh/uv/).
+ *
+ * Якщо `pyproject.toml` у корені відсутній — вихід 0 без запуску інструментів.
+ * Якщо `pyproject.toml` є, але `uv` не знайдено в PATH — це помилка (uv — єдиний
+ * пакет-менеджер, без Poetry).
+ *
+ * Обовʼязкові кроки (uv):
+ *  - `uv lock --check` — lock-файл актуальний щодо `pyproject.toml`;
+ *  - `uv sync --frozen` — середовище зібране строго з `uv.lock`.
+ *
+ * Опційні лінтери запускаються лише якщо доступні через `uv run` (інакше крок
+ * пропускається з повідомленням, як optional vendor-tools у php.mdc). `ruff`
+ * запускається в auto-fix-режимі (мутує робоче дерево, як `markdownlint-cli2 --fix`
+ * у lint-text / `clippy --fix` у lint-rust):
+ *  - `uv run ruff check --fix .`
+ *  - `uv run ruff format .`
+ *  - `uv run mypy .`
+ *
+ * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
+ * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+
+/**
+ * Запускає CLI-крок і репортить результат.
+ * @param {string} label назва кроку для повідомлень
+ * @param {string} cmd абсолютний шлях до CLI
+ * @param {string[]} args аргументи
+ * @param {(msg: string) => void} pass callback pass
+ * @param {(msg: string) => void} fail callback fail
+ * @returns {boolean} true якщо крок успішний
+ */
+function runTool(label, cmd, args, pass, fail) {
+  const r = spawnSync(cmd, args, { stdio: 'inherit', shell: false })
+  if (r.status === 0) {
+    pass(`lint-python: ${label} — OK`)
+    return true
+  }
+  const code = typeof r.status === 'number' ? r.status : 1
+  fail(`lint-python: ${label} — помилка (код ${code}, python.mdc)`)
+  return false
+}
+
+/**
+ * Чи доступний інструмент усередині uv-середовища (`uv run --frozen <tool> --version`).
+ * @param {string} uv абсолютний шлях до `uv`
+ * @param {string} tool назва бінарника (`ruff`, `mypy`)
+ * @returns {boolean} true якщо інструмент відповідає на `--version`
+ */
+function uvToolAvailable(uv, tool) {
+  const r = spawnSync(uv, ['run', '--frozen', tool, '--version'], { stdio: 'ignore', shell: false })
+  return r.status === 0
+}
+
+/**
+ * Внутрішні кроки `lint-python` без локу.
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {number} 0 — OK, 1 — є помилки
+ */
+export function runLintPythonSteps(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+  const { pass, fail } = reporter
+
+  if (!existsSync(join(cwd, 'pyproject.toml'))) {
+    pass('lint-python: немає pyproject.toml у корені — кроки Python пропущено')
+    return reporter.getExitCode()
+  }
+
+  const uv = resolveCmd('uv')
+  if (!uv) {
+    fail('lint-python: `uv` не знайдено в PATH (потрібен при наявному pyproject.toml, python.mdc)')
+    return reporter.getExitCode()
+  }
+
+  if (!runTool('uv lock --check', uv, ['lock', '--check'], pass, fail)) return reporter.getExitCode()
+  if (!runTool('uv sync --frozen', uv, ['sync', '--frozen'], pass, fail)) return reporter.getExitCode()
+
+  /**
+   * Запускає лінтер через `uv run`, якщо він доступний у середовищі.
+   * @param {string} tool назва бінарника
+   * @param {string} label назва кроку
+   * @param {string[]} args аргументи інструмента
+   * @returns {boolean} true, якщо крок успішний або пропущений
+   */
+  function runOptionalUvTool(tool, label, args) {
+    if (!uvToolAvailable(uv, tool)) {
+      pass(`lint-python: ${tool} недоступний у uv-середовищі — крок пропущено`)
+      return true
+    }
+    return runTool(label, uv, ['run', '--frozen', tool, ...args], pass, fail)
+  }
+
+  if (!runOptionalUvTool('ruff', 'ruff check --fix', ['check', '--fix', '.'])) return reporter.getExitCode()
+  if (!runOptionalUvTool('ruff', 'ruff format', ['format', '.'])) return reporter.getExitCode()
+  if (!runOptionalUvTool('mypy', 'mypy', ['.'])) return reporter.getExitCode()
+
+  return reporter.getExitCode()
+}
+
+/**
+ * Публічна CLI-форма: серіалізує через `withLock('lint-python')` + дедуп за станом git-дерева.
+ * @returns {Promise<number>} код виходу
+ */
+export const runLintPython = () => runStandardLint(import.meta.dirname, runLintPythonSteps)
+
+if (isRunAsCli(import.meta.url)) {
+  process.exitCode = await runLintPython()
+}

package/rules/python/meta.json

@@ -0,0 +1 @@
+{ "auto": { "glob": "pyproject.toml" } }

package/rules/python/policy/lint_python_yml/lint_python_yml.rego

@@ -0,0 +1,59 @@
+# Перевірка `.github/workflows/lint-python.yml` для правила python (python.mdc).
+#
+# Канон надходить через --data: { "template": { "snippet": ... } }
+# Структура --data сформована з template/lint-python.yml.snippet.yml.
+# Перевіряємо (drift-safe — усе ведеться з template, без inline-літералів):
+#   - кожен `uses` з template (підмножина): actions/checkout@v6,
+#     ./.github/actions/setup-bun-deps, astral-sh/setup-uv@v8.0.0;
+#   - кожен `run` з template має бути присутнім (як substring) серед run-кроків
+#     input'а: `uv sync --frozen`, `bun run lint-python`.
+# Заборона Poetry-кроків (snok/install-poetry, `poetry install`) — через відсутність
+# у каноні: правило вимагає uv-кроки, а нав'язаних poetry-кроків у template немає.
+# Універсальні workflow-перевірки (name, concurrency, branches) — у `ga.workflow_common`.
+package python.lint_python_yml
+
+import rego.v1
+
+# Усі `uses` з канону workflow (по всіх job'ах template).
+expected_uses contains u if {
+	some job in data.template.snippet.jobs
+	some step in job.steps
+	u := object.get(step, "uses", "")
+	u != ""
+}
+
+# Усі `uses` з input workflow.
+actual_uses contains u if {
+	some job in object.get(input, "jobs", {})
+	some step in object.get(job, "steps", [])
+	u := object.get(step, "uses", "")
+	u != ""
+}
+
+# Конкатенація всіх `run`-кроків з input workflow.
+all_run_text := concat("\n", [run_text |
+	some job in object.get(input, "jobs", {})
+	some step in object.get(job, "steps", [])
+	run_text := step_run_to_text(step)
+])
+
+deny contains msg if {
+	some required_use in expected_uses
+	not required_use in actual_uses
+	msg := sprintf("lint-python.yml: відсутній step з `uses: %s` (python.mdc)", [required_use])
+}
+
+deny contains msg if {
+	some job in data.template.snippet.jobs
+	some step in job.steps
+	expected_run := object.get(step, "run", "")
+	expected_run != ""
+	not contains(all_run_text, expected_run)
+	msg := sprintf("lint-python.yml: жоден крок run не містить %q (python.mdc)", [expected_run])
+}
+
+step_run_to_text(step) := step.run if is_string(step.run)
+
+else := concat("\n", [s | some s in step.run]) if is_array(step.run)
+
+else := ""

package/rules/python/policy/lint_python_yml/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": ".github/workflows/lint-python.yml" }
+}

package/rules/python/policy/lint_python_yml/template/lint-python.yml.snippet.yml

@@ -0,0 +1,41 @@
+name: Lint Python
+
+on:
+  push:
+    branches:
+      - dev
+      - main
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/lint-python.yml'
+
+  pull_request:
+    branches:
+      - dev
+      - main
+
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - uses: ./.github/actions/setup-bun-deps
+
+      - uses: astral-sh/setup-uv@v8.0.0
+
+      - name: Install dependencies (uv)
+        run: uv sync --frozen
+
+      - name: Lint Python
+        run: bun run lint-python

package/rules/python/policy/package_json/package_json.rego

@@ -0,0 +1,16 @@
+# Перевірка `package.json` (python.mdc).
+#
+# Канон надходить через --data: { "template": { "contains": ... } }
+# Структура --data сформована з template/package.json.contains.json.
+# FS-перевірки (наявність `package.json` як такого) — у JS.
+package python.package_json
+
+import rego.v1
+
+deny contains msg if {
+	some script_name, needles in data.template.contains.scripts
+	actual := object.get(object.get(input, "scripts", {}), script_name, "")
+	some needle in needles
+	not contains(actual, needle)
+	msg := sprintf("package.json: scripts.%s має містити %q (python.mdc)", [script_name, needle])
+}

package/rules/python/policy/package_json/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": "package.json" }
+}

package/rules/python/policy/package_json/template/package.json.contains.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "lint-python": ["bun"]
+  }
+}

package/rules/python/policy/pyproject_toml/pyproject_toml.rego

@@ -0,0 +1,39 @@
+# Перевірка `pyproject.toml` (python.mdc).
+#
+# Канон надходить через --data: { "template": { "deny": ... } }
+# Структура --data сформована з template/pyproject.toml.deny.toml.
+# FS-перевірки (`poetry.lock`, `poetry.toml`, `uv.lock`, `package.json`) — у JS.
+#
+# Дві групи правил:
+#   1. Заборона Poetry — `[tool.poetry]` (та інші заборонені під-таблиці `tool`)
+#      керується deny-template, drift-safe.
+#   2. PEP 621 — `[project].name` і `[project].version` обовʼязкові (структурна
+#      вимога без канонічного літералу, тому inline).
+package python.pyproject_toml
+
+import rego.v1
+
+# ── Заборона Poetry (deny-template керує переліком) ──────────────────────────
+
+deny contains msg if {
+	some key, reason in object.get(data.template.deny, "tool", {})
+	key in object.keys(object.get(input, "tool", {}))
+	msg := sprintf("pyproject.toml: [tool.%s] — %s", [key, reason])
+}
+
+# ── PEP 621: обовʼязкові [project].name / [project].version ──────────────────
+
+deny contains msg if {
+	not project_field_set("name")
+	msg := "pyproject.toml: відсутній [project].name (PEP 621 — мігруй з [tool.poetry], python.mdc)"
+}
+
+deny contains msg if {
+	not project_field_set("version")
+	msg := "pyproject.toml: відсутній статичний [project].version (PEP 621, python.mdc)"
+}
+
+project_field_set(key) if {
+	value := object.get(object.get(input, "project", {}), key, "")
+	value != ""
+}

package/rules/python/policy/pyproject_toml/target.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "files": { "single": "pyproject.toml" }
+}

package/rules/python/policy/pyproject_toml/template/pyproject.toml.deny.toml

@@ -0,0 +1,2 @@
+[tool]
+poetry = "Poetry заборонено: мігруй на uv + PEP 621 [project] (python.mdc)"

package/rules/python/policy/pyproject_toml/template/pyproject.toml.snippet.toml

@@ -0,0 +1,12 @@
+# Канонічний цільовий вигляд після міграції з Poetry на uv (PEP 621).
+# Метадані — у [project] (а не [tool.poetry]); dev-залежності додавай через
+# `uv add --dev <pkg>` (uv тримає їх у [dependency-groups].dev або [tool.uv]).
+[project]
+name = "your-package"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = []
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

package/rules/python/python.mdc

@@ -0,0 +1,47 @@
+---
+description: Python — пакет-менеджер uv (без Poetry), PEP 621, lint-python
+globs: "**/*.py,pyproject.toml,uv.lock,.github/workflows/lint-python.yml"
+alwaysApply: false
+version: '1.0'
+---
+
+Python-проєкти ведуться **виключно** на [uv](https://docs.astral.sh/uv/) — єдиний пакет-менеджер і резолвер. **Poetry заборонено.**
+
+- Метадані проєкту — у секції **`[project]`** (PEP 621), а **не** в `[tool.poetry]`.
+- Lock-файл — **`uv.lock`** (коммітиться). `poetry.lock` / `poetry.toml` мають бути відсутні.
+- Залежності: `uv add <pkg>`; dev-залежності: `uv add --dev <pkg>`.
+- Середовище: `uv sync --frozen` (строго з `uv.lock`).
+
+`uv` / `ruff` / `mypy` **не** додаються в кореневі `devDependencies` споживача — це окремий toolchain і ставиться через `astral-sh/setup-uv` у CI або локально (як `composer` / `regal`).
+
+## Міграція з Poetry на uv
+
+1. Прибери `[tool.poetry]` і `poetry.lock` / `poetry.toml`.
+2. Перенеси метадані в `[project]` (name, version, requires-python, dependencies) за PEP 621.
+3. Згенеруй lock: `uv lock` → `uv.lock`.
+4. Dev-залежності: `uv add --dev ruff mypy …`.
+
+Канонічний цільовий вигляд `pyproject.toml`: [pyproject.toml.snippet.toml](./policy/pyproject_toml/template/pyproject.toml.snippet.toml)
+
+Заборонені під-таблиці `[tool.*]` (Poetry): [pyproject.toml.deny.toml](./policy/pyproject_toml/template/pyproject.toml.deny.toml)
+
+## lint-python
+
+Інструменти uv-екосистеми не мають єдиного CLI, що сам обходить репозиторій, тому `lint-python` делегується у JS-скрипт-обгортку (як `lint-php`, `lint-docker`).
+
+- Канон `package.json#scripts.lint-python` (substring requirement): [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
+
+Скрипт `rules/python/lint/lint.mjs`:
+
+- якщо `pyproject.toml` у корені відсутній — вихід 0 (перевірка пропущена);
+- якщо `pyproject.toml` є, але `uv` не знайдено в PATH — це помилка;
+- `uv lock --check` і `uv sync --frozen` — обовʼязкові;
+- `uv run ruff check --fix .` + `uv run ruff format .` — auto-fix (мутують робоче дерево, як `markdownlint-cli2 --fix` у lint-text);
+- `uv run mypy .` — статична перевірка типів;
+- усі `ruff`/`mypy`-кроки запускаються лише якщо інструмент доступний у середовищі (інакше крок пропускається з повідомленням).
+
+## CI: `.github/workflows/lint-python.yml`
+
+- Канон: [lint-python.yml.snippet.yml](./policy/lint_python_yml/template/lint-python.yml.snippet.yml)
+
+Без кроків `poetry install` / `snok/install-poetry` — лише `astral-sh/setup-uv@v8.0.0` + `uv sync --frozen`.

package/scripts/dispatcher/index.mjs

@@ -9,6 +9,7 @@
  */
 import { cancel, repair, resume, run } from './lib/active.mjs'
 import { init, release, verify } from './lib/commands.mjs'
+import { gate } from './lib/gate.mjs'
 import { plan } from './lib/plan.mjs'
 import { review } from './lib/review.mjs'
 import { spec } from './lib/spec.mjs'
@@ -20,6 +21,7 @@ const USAGE = [
   '  npx @nitra/cursor flow plan [--panel]     # Фасад A: фаза плану → docs/plans/<…> + state',
   '  npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)',
   '  npx @nitra/cursor flow review             # Фасад A: adversarial diff-review (за level)',
+  '  npx @nitra/cursor flow gate               # Фасад A: вердикт PASS/CONCERNS/FAIL (verify+review)',
   '  npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot',
   '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
   '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
@@ -28,13 +30,13 @@ const USAGE = [
 ].join('\n')
 
 /** Підкоманди flow. */
-export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'release', 'run', 'resume', 'cancel', 'repair']
+export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'gate', 'release', 'run', 'resume', 'cancel', 'repair']
 
 /**
  * Усі handler-и реальні (Ф1 Spec/Plan + Ф2 Турнікет + Ф4 Активний Раннер).
  * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
  */
-export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, release, run, resume, cancel, repair }
+export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, gate, release, run, resume, cancel, repair }
 
 /**
  * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й

package/scripts/dispatcher/lib/commands.mjs

@@ -179,6 +179,10 @@ export async function release(rest, deps = {}) {
     log('release: стану нема — спершу `flow init`')
     return 1
   }
+  // М'які ворота: FAIL-гейт — лише попередження, рішення за людиною.
+  if (state.gate?.verdict === 'FAIL') {
+    log(`⚠️ release: gate = FAIL (score ${state.gate.score}) — релізиш свідомо? (див. flow gate)`)
+  }
 
   const ch = run('npx', ['@nitra/cursor', 'change', ...rest], { cwd })
   if ((ch.status ?? 1) !== 0) {

package/scripts/dispatcher/lib/gate.mjs

@@ -0,0 +1,83 @@
+/**
+ * `flow gate` — структурований вердикт релізної готовності (ідея BMAD qa-gate, у
+ * нашому стані). Синтезує механічні гейти `verify` (`state.gates`) і adversarial
+ * findings `review` (`state.review.findings`) у єдине PASS/CONCERNS/FAIL + score
+ * + причини. Дає traceability «чому готово/не готово». `gate` лише агрегує —
+ * рішення verify/review не дублює.
+ *
+ * Уся IO (`now`) ін'єктується; `computeGate` — чиста (тестується без стану на диску).
+ */
+import { cwd as processCwd } from 'node:process'
+
+import { flowEventsPath } from './events.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+
+/** Штрафи score за кожен тип проблеми. */
+const PENALTY = { failedGate: 40, high: 25, med: 8, noVerify: 15 }
+
+/**
+ * Чистий синтез вердикту з наявного стану.
+ * @param {{ gates?: { name: string, ok: boolean }[], review?: { findings?: { severity?: string }[] } }} state стан flow
+ * @returns {{ verdict: 'PASS' | 'CONCERNS' | 'FAIL', score: number, reasons: string[] }} вердикт
+ */
+export function computeGate(state) {
+  const gates = state.gates ?? []
+  const findings = state.review?.findings ?? []
+  const failedGates = gates.filter(g => !g.ok)
+  const high = findings.filter(f => f.severity === 'high')
+  const med = findings.filter(f => f.severity === 'med')
+  const noVerify = gates.length === 0
+
+  const reasons = []
+  for (const g of failedGates) reasons.push(`gate «${g.name}» провалено`)
+  if (high.length > 0) reasons.push(`${high.length} high-severity review finding(s)`)
+  if (med.length > 0) reasons.push(`${med.length} med-severity review finding(s)`)
+  if (noVerify) reasons.push('verify ще не запускався')
+
+  let verdict = 'PASS'
+  if (failedGates.length > 0 || high.length > 0) {
+    verdict = 'FAIL'
+  } else if (med.length > 0 || noVerify) {
+    verdict = 'CONCERNS'
+  }
+
+  const penalty =
+    PENALTY.failedGate * failedGates.length +
+    PENALTY.high * high.length +
+    PENALTY.med * med.length +
+    (noVerify ? PENALTY.noVerify : 0)
+  const score = Math.max(0, Math.min(100, 100 - penalty))
+
+  return { verdict, score, reasons }
+}
+
+/**
+ * `flow gate` — обчислює й фіксує вердикт у `.flow.json`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{ cwd?: string, log?: (m: string) => void, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (FAIL → 1; PASS/CONCERNS → 0)
+ */
+export async function gate(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const now = deps.now ?? Date.now
+
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('gate: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  const result = computeGate(state)
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'gate', verdict: result.verdict },
+    s => ({ ...s, gate: { ...result, at: new Date(now()).toISOString() } }),
+    now
+  )
+
+  log(`gate: ${result.verdict} (score ${result.score})`)
+  for (const r of result.reasons) log(`  · ${r}`)
+  return result.verdict === 'FAIL' ? 1 : 0
+}