@nitra/cursor 3.4.0 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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
+
+- worktree add: перевіряє зайнятість назви й автоматично обирає вільну (base, base2, base3, …) замість падіння на 'a branch named … already exists'
+
 ## [3.4.0] - 2026-06-01
 
 ### Added

package/package.json

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

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/lib/worktree.mjs

@@ -24,13 +24,39 @@ export function sanitizeBranch(branch) {
   if (typeof branch !== 'string' || branch.trim() === '') {
     throw new Error('worktree: імʼя гілки обовʼязкове')
   }
-  const sanitized = branch.trim().replace(UNSAFE_PATH_CHARS_RE, '-').replace(/^-+|-+$/gu, '')
+  const sanitized = branch
+    .trim()
+    .replace(UNSAFE_PATH_CHARS_RE, '-')
+    .replace(/^-+|-+$/gu, '')
   if (sanitized === '') {
     throw new Error(`worktree: імʼя гілки "${branch}" не містить допустимих символів`)
   }
   return sanitized
 }
 
+/**
+ * Перша вільна назва гілки за конвенцією `base`, `base2`, `base3`, … —
+ * суфікс просто число без розділювача (як `main-fix` → `main-fix2`).
+ * Дає змогу `worktree add` спершу перевірити зайнятість і обрати назву,
+ * що спрацює, замість падіння на `fatal: a branch named '…' already exists`.
+ * @param {string} branch бажане імʼя гілки
+ * @param {(candidate: string) => boolean} isTaken чи зайнята назва (гілка/worktree вже існують)
+ * @param {number} [limit] стеля кількості спроб (захист від нескінченного циклу)
+ * @returns {string} перша вільна назва (= `branch`, якщо вона вільна)
+ */
+export function firstFreeBranch(branch, isTaken, limit = 1000) {
+  if (typeof branch !== 'string' || branch.trim() === '') {
+    throw new Error('worktree: імʼя гілки обовʼязкове')
+  }
+  const base = branch.trim()
+  if (!isTaken(base)) return base
+  for (let n = 2; n <= limit; n++) {
+    const candidate = `${base}${n}`
+    if (!isTaken(candidate)) return candidate
+  }
+  throw new Error(`worktree: не знайдено вільної назви для "${base}" за ${limit} спроб`)
+}
+
 /**
  * Детерміновані шляхи checkout і файла-опису для гілки.
  * @param {string} repoRoot абсолютний корінь репозиторію

package/scripts/worktree-cli.mjs

@@ -16,7 +16,7 @@ import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
 import { cleanupFlowSiblings } from './dispatcher/lib/state-store.mjs'
-import { buildDescription, findOrphanDescFiles, worktreePaths } from './lib/worktree.mjs'
+import { buildDescription, findOrphanDescFiles, firstFreeBranch, worktreePaths } from './lib/worktree.mjs'
 
 const USAGE = [
   'Usage:',
@@ -89,20 +89,34 @@ function cmdAdd(rest, ctx) {
     ctx.logError('worktree add: опис обовʼязковий — `worktree add <branch> "<опис>"`')
     return 1
   }
+  // Зайнята, якщо вже є git-гілка з такою назвою або checkout-каталог `.worktrees/<sanit>`.
+  const isTaken = name => {
+    if (git(['show-ref', '--verify', '--quiet', `refs/heads/${name}`], ctx.cwd).status === 0) return true
+    try {
+      return existsSync(worktreePaths(ctx.cwd, name).checkout)
+    } catch {
+      return false // невалідна для шляху назва — впаде нижче на worktreePaths(chosen) з людинозрозумілим текстом
+    }
+  }
+  let chosen
   let paths
   try {
-    paths = worktreePaths(ctx.cwd, branch)
+    chosen = firstFreeBranch(branch, isTaken)
+    paths = worktreePaths(ctx.cwd, chosen)
   } catch (error) {
     ctx.logError(error.message)
     return 1
   }
-  const added = git(['worktree', 'add', paths.checkout, '-b', branch], ctx.cwd)
+  if (chosen !== branch) {
+    ctx.log(`ℹ️  гілка/worktree "${branch}" уже існує — обрано вільну назву "${chosen}"`)
+  }
+  const added = git(['worktree', 'add', paths.checkout, '-b', chosen], ctx.cwd)
   if (added.status !== 0) {
     ctx.logError(`worktree add не вдався: ${added.stderr.trim()}`)
     return 1
   }
   const baseCommit = git(['rev-parse', '--short', 'HEAD'], ctx.cwd).stdout.trim()
-  const md = buildDescription({ branch, task, baseCommit, date: today(ctx.now) })
+  const md = buildDescription({ branch: chosen, task, baseCommit, date: today(ctx.now) })
   writeFileSync(paths.descFile, md, 'utf8')
   ctx.log(`✅ worktree: ${paths.checkout}`)
   ctx.log(`   опис:    ${paths.descFile}`)