@7n/rules 1.12.0 → 1.13.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.13.1] - 2026-07-18
+
+### Changed
+
+- doc-files: виключити Storybook *.stories.* файли з обов'язкової генерації docs/<stem>.md (той самий glob-список, що *.test.*/*.spec.*/*.d.ts)
+
+## [1.13.0] - 2026-07-17
+
+### Added
+
+- `skill pi/cursor/codex taze` — Python/uv-гілку (`pyproject.toml`) тепер теж покриває оркестратор: детермінований `collectUvDiff` (`npm/skills/taze/js/uv-diff.mjs`, парсинг PEP 508/PEP 440 через `smol-toml`, той самий caret-семантики принцип, що й для npm/Cargo) замість ручної класифікації. Bump — по кожній прямій залежності `uv remove` + `uv add --bounds lower` (`uv` не має єдиної команди для major-стрибка), і по одному ізольованому виклику раннера на кожен major-пакет. Якщо `uv` не встановлено — Python-гілка пропускається без блокування npm/Rust-гілок (pyproject.toml лишається в звіті)
+
 ## [1.12.0] - 2026-07-17
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/doc-files/docgen-scan/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-scan/main.mjs
 docgen:
-  crc: 23cec34d
+  crc: 6b2177db
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-scan/main.mjs

@@ -9,8 +9,8 @@ import { parseDocFrontmatter, readDocCrc, staleness } from '../docgen-crc/main.m
 /** Кодові розширення, для яких генеруємо документацію. */
 const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py', '.rs'])
 
-/** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
-const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
+/** `*.test.*`, `*.spec.*`, `*.stories.*` — тести й Storybook CSF-файли, документувати не треба. */
+const TEST_FILE_RE = /\.(?:test|spec|stories)\.[^.]+$/u
 
 /**
  * Чи корінь має system-wide docs layout.

package/skills/taze/SKILL.md

@@ -1,32 +1,34 @@
 ---
 name: n-taze
 description: >-
-  Оновлення версій модулів проекту (bun/npm і, якщо є Cargo.toml, Rust-крейти
-  через cargo-edit) з аналізом major-змін і автоматичним рефакторингом
-  несумісного коду
-version: '1.1'
+  Оновлення версій модулів проекту (bun/npm; якщо є Cargo.toml — Rust-крейти
+  через cargo-edit; якщо є pyproject.toml — Python-пакети через uv) з
+  аналізом major-змін і автоматичним рефакторингом несумісного коду
+version: '1.2'
 ---
 
 # n-taze — Оновлення версій проекту
 
 ## Мета
 
-Оновити всі модулі проекту (npm/bun-залежності, а за наявності `Cargo.toml` — і Rust-крейти) до останніх версій, виявити major-оновлення, перевірити сумісність змін з кодом проекту і за потреби зрефакторити несумісні місця.
+Оновити всі модулі проекту (npm/bun-залежності, а за наявності `Cargo.toml`/`pyproject.toml` — і Rust-крейти/Python-пакети) до останніх версій, виявити major-оновлення, перевірити сумісність змін з кодом проекту і за потреби зрефакторити несумісні місця.
 
-## Оркестрація (npm/bun- і Rust-гілка) — не одним промптом
+## Оркестрація (npm/bun-, Rust- і Python-гілка) — не одним промптом
 
 `npx @7n/rules skill pi|cursor|codex taze` **не** передає цей файл одним суцільним
 промптом в один агентський хід — так робив старий дизайн, і саме тому реальний
 прогін міг зависати без жодної діагностики (один величезний непрозорий хід на
 весь монорепо, без проміжних зупинок для перевірки прогресу). Замість цього `npm/skills/taze/js/orchestrate.mjs`:
 
-1. Детерміновано, без LLM, виконує кроки 1-3 нижче для обох гілок: npm/bun (бекап → `bunx taze -w -r latest` → `bun install` → `n-rules taze diff`) і, якщо знайдені `Cargo.toml`, Rust (бекап → `cargo upgrade --incompatible allow` → `cargo update` → `collectCargoDiff` з `cargo-diff.mjs`, детермінований cargo-еквівалент `n-rules taze diff` — парсить кожен `Cargo.toml` через `smol-toml`, класифікує major за тим самим правилом caret-семантики, включно з Cargo-скороченими версіями `"1"`/`"0.4"`).
-2. Для кожного **окремого** major-пакета/крейта з diff-у — один ізольований, обмежений виклик обраного раннера (кроки 4-6, лише для цього запису; промпт генерує `buildDependencyPrompt`/`buildCargoDependencyPrompt`, не цей SKILL.md).
+1. Детерміновано, без LLM, виконує кроки 1-3 нижче для всіх гілок: npm/bun (бекап → `bunx taze -w -r latest` → `bun install` → `n-rules taze diff`); якщо знайдені `Cargo.toml`, Rust (бекап → `cargo upgrade --incompatible allow` → `cargo update` → `collectCargoDiff` з `cargo-diff.mjs`, детермінований cargo-еквівалент `n-rules taze diff` — парсить кожен `Cargo.toml` через `smol-toml`, класифікує major за тим самим правилом caret-семантики, включно з Cargo-скороченими версіями `"1"`/`"0.4"`); якщо знайдений кореневий `pyproject.toml`, Python (бекап → по кожній прямій залежності `uv remove <pkg>` + `uv add <pkg>[extras] --bounds lower` → `collectUvDiff` з `uv-diff.mjs`, парсить PEP 508/PEP 440 через `smol-toml`, той самий caret-принцип класифікації).
+2. Для кожного **окремого** major-пакета/крейта з diff-у — один ізольований, обмежений виклик обраного раннера (кроки 4-6, лише для цього запису; промпт генерує `buildDependencyPrompt`/`buildCargoDependencyPrompt`/`buildUvDependencyPrompt`, не цей SKILL.md).
 3. Детерміновано прибирає бекапи (крок 7) і компонує звіт (крок 8) з результатів усіх ітерацій.
 
 Якщо `Cargo.toml` знайдені, але `cargo-edit` не встановлено — Rust-гілка **не**
-блокує npm-гілку: оркестратор пропускає Rust-обробку і в звіті перелічує
-знайдені `Cargo.toml` як такі, що потребують ручного прогону (нижче).
+блокує інші гілки: оркестратор пропускає Rust-обробку і в звіті перелічує
+знайдені `Cargo.toml` як такі, що потребують ручного прогону (нижче). Так само,
+якщо `pyproject.toml` знайдений, але `uv` не встановлено — Python-гілка **не**
+блокує інші гілки.
 
 Переваги: падіння/timeout на одному пакеті/крейті не втрачає прогрес по інших;
 кожен виклик успадковує власний timeout раннера (короткий, бо скоуп малий —
@@ -34,14 +36,15 @@ version: '1.1'
 
 Кроки 1-8 нижче лишаються джерелом правди щодо ЗМІСТУ роботи (що саме робить
 кожен крок) — оркестратор їх виконує програмно (1-3/7/8) або як промпт на
-один запис (4-6) для обох гілок.
+один запис (4-6) для всіх гілок.
 
 ## Передумови
 
 - Чисте робоче дерево (`git status` без незакомічених змін у `package.json` / `bun.lock` / `node_modules`) — інакше різницю не відрізнити від оновлення.
 - Встановлений `bun` і доступний `bunx`.
 - Запуск з кореня проекту (де лежить `package.json` / `bun.lock`).
-- Якщо в проекті є хоч один `Cargo.toml` (не в `node_modules`/`.worktrees`) — бажано встановлений `cargo-edit` (`cargo install cargo-edit`, дає команду `cargo upgrade`). Без нього major-бампи Rust-залежностей неможливо застосувати детерміновано (голий `cargo update` піднімає лише semver-сумісні версії) — оркестратор пропускає Rust-гілку (без блокування npm-гілки) і перелічує знайдені `Cargo.toml` у звіті як такі, що потребують ручного прогону кроків 2-8 нижче.
+- Якщо в проекті є хоч один `Cargo.toml` (не в `node_modules`/`.worktrees`) — бажано встановлений `cargo-edit` (`cargo install cargo-edit`, дає команду `cargo upgrade`). Без нього major-бампи Rust-залежностей неможливо застосувати детерміновано (голий `cargo update` піднімає лише semver-сумісні версії) — оркестратор пропускає Rust-гілку (без блокування інших гілок) і перелічує знайдені `Cargo.toml` у звіті як такі, що потребують ручного прогону кроків 2-8 нижче.
+- Якщо в проекті є кореневий `pyproject.toml` — бажано встановлений `uv`. Без нього major-бампи Python-залежностей неможливо застосувати детерміновано — оркестратор пропускає Python-гілку (без блокування інших гілок) і перелічує `pyproject.toml` у звіті як такий, що потребує ручного прогону кроків 2-8 нижче.
 
 ### 0.2. Детекція Rust-крейтів
 
@@ -51,6 +54,14 @@ find . -name Cargo.toml -not -path "*/node_modules/*" -not -path "*/.worktrees/*
 
 Якщо список непорожній — паралельно з npm-гілкою виконуються кроки 1–8 у Rust-варіанті (позначені нижче як «Rust-гілка»). Якщо порожній — Rust-кроки повністю пропускаються.
 
+### 0.3. Детекція Python/uv-проекту
+
+```bash
+test -f pyproject.toml && echo pyproject.toml
+```
+
+v1: лише кореневий `pyproject.toml` (uv-конвенція single-project, без обходу workspace-членів, на відміну від Cargo). Якщо файл існує — паралельно виконуються кроки 1–8 у Python-варіанті (позначені нижче як «Python-гілка»). Якщо відсутній — Python-кроки повністю пропускаються.
+
 ## Workflow
 
 ### 1. Зафіксувати стартовий стан
@@ -71,6 +82,13 @@ cp Cargo.toml Cargo.toml.taze-bak
 cp Cargo.lock Cargo.lock.taze-bak   # якщо lock-файл спільний на workspace — достатньо одного бекапу в корені
 ```
 
+**Python-гілка** — якщо на кроці 0.3 знайдений `pyproject.toml`:
+
+```bash
+cp pyproject.toml pyproject.toml.taze-bak
+cp uv.lock uv.lock.taze-bak   # якщо є
+```
+
 ### 2. Запустити оновлення
 
 ```bash
@@ -92,6 +110,17 @@ cargo update
 - `cargo upgrade` (з `cargo-edit`) переписує вимоги версій у кожному `Cargo.toml` workspace-у на останні; `--incompatible allow` явно дозволяє перетинати major-межу (аналог `-r latest` у taze) — без цього флага incompatible-оновлення за замовчуванням ігноруються.
 - `cargo update` після цього синхронізує `Cargo.lock` з новими вимогами.
 
+**Python-гілка:**
+
+```bash
+for pkg in $(<список прямих залежностей із [project].dependencies>); do
+  uv remove "$pkg"
+  uv add "$pkg" --bounds lower
+done
+```
+
+`uv` **не має** єдиної команди "підняти все до latest, навіть через major" (на відміну від `bunx taze -w -r latest`/`cargo upgrade --incompatible allow`) — підтверджено емпірично: `uv add <pkg>` на вже присутній залежності НЕ переписує specifier без попереднього `uv remove`. `--bounds lower` записує нижню межу без верхньої (`>=<latest>`), коректно зберігає `[extras]`. Провал одного пакета (мережа/резолюція) не втрачає прогрес по інших — оркестратор best-effort відновлює оригінальний рядок, якщо `uv add` не вдався після `uv remove`.
+
 ### 3. Виявити major-оновлення
 
 > **Не порівнюй `package.json` вручну.** Класифікацію semver несе CLI — детерміновано, по всіх воркспейсах.
@@ -106,6 +135,8 @@ n-rules taze diff
 
 **Rust-гілка (оркестровано)** — `collectCargoDiff` (`npm/skills/taze/js/cargo-diff.mjs`) робить те саме детерміновано: парсить кожен `Cargo.toml.taze-bak`/`Cargo.toml` через `smol-toml`, порівнює `dependencies`/`dev-dependencies`/`build-dependencies` (рядок чи `{ version = "...", features = [...] }`), класифікує за тим самим правилом caret-семантики — Cargo-скорочені версії (`"1"`, `"0.4"`) трактуються як відсутні компоненти = 0. Ручний прогін поза оркестратором — той самий принцип: `diff Cargo.toml.taze-bak Cargo.toml` по рядках `<name> = "<version>"`.
 
+**Python-гілка (оркестровано)** — `collectUvDiff` (`npm/skills/taze/js/uv-diff.mjs`) робить те саме детерміновано: парсить `pyproject.toml.taze-bak`/`pyproject.toml` через `smol-toml`, порівнює `[project].dependencies` (масив PEP 508-рядків, матчинг за іменем пакета — не за позицією), дістає нижню межу PEP 440-специфікатора (`extractLowerBoundVersion`) і класифікує за тим самим правилом caret-семантики. Ручний прогін поза оркестратором — той самий принцип: `diff pyproject.toml.taze-bak pyproject.toml` по записах `[project].dependencies`.
+
 ### 4. Зібрати breaking changes по кожному major-оновленню
 
 Для кожного модуля зі списку зібрати фактичні відмінності одним з джерел (у порядку пріоритету):
@@ -118,6 +149,8 @@ n-rules taze diff
 
 **Rust-гілка** — адресу репозиторію взяти з поля `repository`/`documentation` крейта на `crates.io` (`https://crates.io/crates/<name>`) або з `[package.metadata]`; CHANGELOG зазвичай у `CHANGELOG.md` репозиторію або в GitHub Releases. Якщо немає — `cargo doc` різниця по публічному API (`pub fn`/`pub struct`/`pub trait`) між закешованою старою версією (`~/.cargo/registry/src/*/<name>-<old-version>/`) і новою (`~/.cargo/registry/src/*/<name>-<new-version>/`) через `diff -r src/`.
 
+**Python-гілка** — адресу репозиторію взяти зі сторінки `https://pypi.org/project/<name>/` (поле "Homepage"/"Source"); CHANGELOG зазвичай у `CHANGELOG.md`/`HISTORY.md` репозиторію або в GitHub Releases. Якщо немає — різниця по публічному API між закешованою старою версією (`~/.cache/uv/`) і новою (`.venv/lib/python*/site-packages/<name>/`).
+
 ### 5. Перевірити сумісність з кодом проекту
 
 Для кожного breaking change знайти його використання в коді проекту:
@@ -139,6 +172,14 @@ rg -n "<use-шлях|функція|макрос>" --type rust
 
 Та сама класифікація сумісно/несумісно.
 
+**Python-гілка:**
+
+```bash
+rg -n "<імпорт|функція|клас>" --type py
+```
+
+Та сама класифікація сумісно/несумісно.
+
 ### 6. Рефакторинг несумісних місць
 
 Для кожного несумісного місця — застосувати міграцію згідно з changelog модуля (перейменувати імпорт, оновити сигнатуру виклику, замінити видалену опцію еквівалентом тощо). Після правок:
@@ -157,6 +198,14 @@ cargo clippy --all-targets --all-features -- -D warnings
 cargo test
 ```
 
+**Python-гілка** — після правок (залежно від того, що реально налаштовано в проєкті):
+
+```bash
+ruff check .
+mypy .
+pytest
+```
+
 Якщо міграція нетривіальна або неоднозначна — **не вгадувати**, залишити TODO у коді з посиланням на CHANGELOG і винести в підсумковий звіт як ручну дію.
 
 ### 7. Прибрати тимчасові файли
@@ -175,6 +224,12 @@ rm Cargo.toml.taze-bak Cargo.lock.taze-bak
 
 (І бекапи по кожному workspace-члену, якщо створювались окремо.)
 
+**Python-гілка:**
+
+```bash
+rm pyproject.toml.taze-bak uv.lock.taze-bak
+```
+
 ### 8. Звіт користувачу
 
 Коротко в одному повідомленні:
@@ -185,11 +240,12 @@ rm Cargo.toml.taze-bak Cargo.lock.taze-bak
 - **Потребує ручного втручання:** список TODO з причиною (нетривіальна міграція / неоднозначність / падіння тестів).
 - **Стан перевірок:** `lint` / `typecheck` / `test` — pass/fail з номером рядка, де впало.
 
-Якщо на кроці 0.2 знайдені Rust-крейти — додати окрему секцію **Rust-крейти** з тим самим переліком (оновлено / major / зрефакторено / потребує ручного втручання), і в **Стан перевірок** — окремо `cargo fmt` / `cargo clippy` / `cargo test`.
+Якщо на кроці 0.2 знайдені Rust-крейти — додати окрему секцію **Rust-крейти** з тим самим переліком (оновлено / major / зрефакторено / потребує ручного втручання), і в **Стан перевірок** — окремо `cargo fmt` / `cargo clippy` / `cargo test`. Якщо на кроці 0.3 знайдений `pyproject.toml` — так само окрема секція **Python-пакети (uv)**, і в **Стан перевірок** — окремо `ruff` / `mypy` / `pytest`.
 
 ## Примітка
 
 - Не запускати `npx @7n/rules lint` паралельно з іншими ESLint-задачами — діє правило з кореневого `CLAUDE.md`.
 - Якщо проект — `npm/` пакет цього репо, після змін у `package.json` / коді треба підняти `version` і додати запис у `CHANGELOG.md` згідно з `npm/CLAUDE.md`.
-- При великій кількості major-оновлень розбити PR по одному модулю на коміт — щоб `git bisect` залишався корисним. Це стосується і Rust-крейтів окремо від npm-пакетів.
+- При великій кількості major-оновлень розбити PR по одному модулю на коміт — щоб `git bisect` залишався корисним. Це стосується і Rust-крейтів, і Python-пакетів окремо від npm-пакетів.
 - `cargo upgrade --incompatible allow` редагує `Cargo.toml` навіть для залежностей без доступних breaking changes в змінах API — завжди звіряй крок 4 (CHANGELOG) перед тим, як вважати оновлення безпечним, а не лише факт успішної компіляції.
+- `uv add <pkg>` на вже присутній залежності — no-op (specifier НЕ переписується); детерміновану гілку це не блокує (вона робить `uv remove` спершу), але при ручному прогоні кроків 2-8 легко про це забути.

package/skills/taze/js/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/skills/taze/js/
 | [cargo-diff.mjs](cargo-diff.md)   | JS Module |
 | [diff.mjs](diff.md)               | JS Module |
 | [orchestrate.mjs](orchestrate.md) | JS Module |
+| [uv-diff.mjs](uv-diff.md)         | JS Module |

package/skills/taze/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/skills/taze/js/orchestrate.mjs
 docgen:
-  crc: 1ff52a80
+  crc: 56fd9864
   model: openai-codex/gpt-5.4-mini
   score: 100
   issues: judge:inaccurate:0.98
@@ -12,32 +12,34 @@ docgen:
 
 ## Огляд
 
-Файл об’єднує публічні дії `buildDependencyPrompt`, `callRunner`, `backupWorkspacePackageFiles`, `cleanupBackups`, `findCargoManifests`, `formatReport`, `runTazeOrchestrator`, щоб узгодити оновлення залежностей за даними з `main.json` і `package.json`. Він працює read-only: не пише у ФС/БД, має кешування в межах прогону, свідомо пропускає шляхи `node_modules`, тимчасово зберігає бекапи `package.json` у воркспейсах і прибирає їх після завершення. Результат проходу оформлюється через `formatReport` як підсумок змін і стану оновлення.
+Оркеструє `taze` для трьох екосистем — npm/bun, Rust (Cargo) і Python (uv) — детерміновано, без LLM: бекап маніфестів → масовий bump (`bunx taze`/`cargo upgrade`/по-пакетний `uv remove`+`uv add --bounds lower`) → diff класифікація major vs minor/patch → прибирання бекапів → Markdown-звіт (`formatReport`). Для КОЖНОГО окремого major-пакета/крейта з diff-у виконує один ізольований, обмежений виклик обраного раннера (`buildDependencyPrompt`/`buildCargoDependencyPrompt`/`buildUvDependencyPrompt` + `callRunner`) — лише перевірка сумісності й рефакторинг, не сам bump. Файл виконує реальні файлові операції (копіює/видаляє бекапи `package.json`/`Cargo.toml`/`Cargo.lock`/`pyproject.toml`/`uv.lock`) і запускає зовнішні команди (`bunx`, `bun`, `cargo`, `uv`, `git`, `find`) — не read-only.
 
 ## Поведінка
 
-- **buildDependencyPrompt** — формує текст завдання для перевірки major-оновлення одного пакета й подальшого сумісного рефакторингу.
-- **callRunner** — запускає один ітеративний LLM-виклик у вибраному раннері та повертає результат разом із зібраним текстом відповіді.
-- **backupWorkspacePackageFiles** — створює тимчасові бекапи `package.json` у воркспейсах для подальшого порівняння змін.
-- **cleanupBackups** — прибирає тимчасові бекапи `package.json` після завершення прогону.
-- **findCargoManifests** — знаходить `Cargo.toml` поза `node_modules`, `.worktrees` і `target` для інформаційного підсумку.
-- **formatReport** — збирає лаконічний Markdown-звіт про minor/patch, major-оновлення, Rust-крейти та загальний обсяг змін.
-- **runTazeOrchestrator** — виконує повний прогін taze: перевіряє worktree з `main.json`, робить бекап, оновлює залежності з `package.json`, обробляє major-оновлення по одному пакету, прибирає бекапи й повертає підсумок.
+- **buildDependencyPrompt** / **buildCargoDependencyPrompt** / **buildUvDependencyPrompt** — формують промпт ОДНОГО ітеративного виклику (лише перевірка сумісності й рефакторинг) для одного major-пакета npm/Cargo/uv відповідно.
+- **callRunner** — диспетчер одного ітеративного виклику: `pi` — вбудований pi-агент (текст через `deps.out`), `cursor`/`codex` — napi-міст ACP (`@7n/llm-lib/acp`).
+- **backupWorkspacePackageFiles** / **cleanupBackups** — бекап і прибирання `package.json` кожного воркспейсу.
+- **backupCargoManifests** / **cleanupCargoBackups** — бекап і прибирання кожного `Cargo.toml` + спільного кореневого `Cargo.lock`.
+- **backupUvManifest** / **cleanupUvBackups** — бекап і прибирання кореневого `pyproject.toml` + `uv.lock`.
+- **findCargoManifests** — знаходить усі `Cargo.toml` поза `node_modules`/`.worktrees`/`target`.
+- **findPyprojectManifest** — перевіряє наявність кореневого `pyproject.toml` (uv-конвенція — один файл, не per-package обхід).
+- **formatReport** — компонує підсумковий Markdown-звіт (minor/patch, major-оновлення по кожній з трьох гілок, загальний обсяг змін) без окремого LLM-виклику.
+- **runTazeOrchestrator** — повний прогін: перевіряє, що `cwd` — ізольований worktree, послідовно обробляє npm-, Rust- (за наявності `Cargo.toml` і `cargo-edit`) і Python-гілку (за наявності `pyproject.toml` і `uv`) — бекап → bump → diff → ізольовані виклики раннера по кожному major-запису → прибирання — і повертає звіт.
 
 ## Публічний API
 
-- buildDependencyPrompt — Готує промпт для одного LLM-кроку taze: тільки breaking changes, сумісність і рефакторинг для одного major-пакета. Перші кроки аналізу та фінальну збірку звіту робить оркестратор без LLM.
-- callRunner — Запускає один ітеративний виклик через вибраний раннер. Для `pi` бере текст із stdout вбудованого pi-агента, для `cursor` і `codex` отримує його напряму через ACP-міст.
-- backupWorkspacePackageFiles — Зберігає копії `package.json` усіх workspace-пакетів перед змінами, щоб потім відрізнити major і minor оновлення.
-- cleanupBackups — Видаляє тимчасові копії `package.json` після завершення роботи.
-- findCargoManifests — Находить `Cargo.toml` у репозиторії поза службовими директоріями; використовується лише для огляду Rust-крейтів.
-- formatReport — Складає фінальний звіт із результатів усіх ітерацій без окремого LLM-запиту.
-- runTazeOrchestrator — Керує taze від початку до кінця: робить бекап, масово оновлює версії, збирає diff, прибирає тимчасові файли й формує звіт. Для кожного major-пакета окремо запускає обмежений LLM-виклик, щоб збій одного пакета не зупиняв інші.
-
-Конфіги: `package.json`, `main.json`
+- buildDependencyPrompt / buildCargoDependencyPrompt / buildUvDependencyPrompt — промпт одного major-запису відповідної екосистеми.
+- callRunner — виклик обраного раннера (`pi`/`cursor`/`codex`) з одним промптом.
+- backupWorkspacePackageFiles / cleanupBackups — бекап/прибирання `package.json` воркспейсів.
+- backupCargoManifests / cleanupCargoBackups — бекап/прибирання `Cargo.toml`/`Cargo.lock`.
+- backupUvManifest / cleanupUvBackups — бекап/прибирання `pyproject.toml`/`uv.lock`.
+- findCargoManifests — список знайдених `Cargo.toml` у репозиторії.
+- findPyprojectManifest — список (0 або 1 запис) кореневого `pyproject.toml`.
+- formatReport — фінальний Markdown-звіт із результатів усіх трьох гілок.
+- runTazeOrchestrator — повна оркестрація taze для npm/bun + Rust + Python.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
-- Кешує результати в межах одного прогону.
-- Свідомо пропускає шляхи: `node_modules`.
+- Виконує файлові операції (копіювання/видалення бекапів) і запускає зовнішні команди — НЕ read-only.
+- Перед будь-якою мутацією перевіряє, що `cwd` — ізольований worktree (`assertRunningInWorktree`), інакше кидає виняток.
+- Падіння одного пакета/крейта в ізольованому виклику раннера не втрачає прогрес по інших записах.

package/skills/taze/js/docs/uv-diff.md

@@ -0,0 +1,41 @@
+---
+type: JS Module
+title: uv-diff.mjs
+resource: npm/skills/taze/js/uv-diff.mjs
+docgen:
+  crc: a23e68cc
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Працює з залежностями `pyproject.toml` у форматах PEP 508 і PEP 440: `parsePep508` і `parsePep440Version` розбирають записи, `extractLowerBoundVersion` дістає нижню межу версії, `diffPyprojectDeps` і `collectUvDiff` порівнюють прямі залежності та формують diff відносно backup-версії, а `listDirectDependencies` повертає список прямих залежностей. Код read-only (лише читає файли з диска), fail-safe перехоплює помилки без винятків назовні та для частини збоїв повертає порожнє значення замість помилки.
+
+## Поведінка
+
+- `parsePep508` — розбирає рядок залежності у форматі PEP 508 на назву пакета, extras і version specifier; для невалідного рядка повертає порожній результат.
+- `parsePep440Version` — витягує ядро версії PEP 440 і зводить відсутні компоненти до нулів; для не-версійного рядка повертає порожній результат.
+- `extractLowerBoundVersion` — дістає нижню межу версійного specifier-а, тобто версію, яку відповідає нижньому bound у залежності; якщо межі немає, повертає порожній результат.
+- `diffPyprojectDeps` — порівнює прямі залежності двох `pyproject.toml` за іменем пакета і класифікує зміну як major або minor/patch.
+- `collectUvDiff` — збирає diff для `pyproject.toml` між поточним файлом і його backup-версією, а за відсутності потрібних файлів повертає порожній diff.
+- `listDirectDependencies` — повертає список прямих залежностей із `pyproject.toml` у вигляді назв пакетів та extras.
+
+## Публічний API
+
+- parsePep508 — Розбирає один PEP 508-запис залежності на назву пакета, extras і version specifier.
+- parsePep440Version — Виділяє основні компоненти PEP 440-версії; відсутні частини вважає нулями.
+- extractLowerBoundVersion — Витягає найнижчу допустиму версію з набору `>=` / `==` / `~=`-обмежень.
+- diffPyprojectDeps — Порівнює списки `[project].dependencies` у двох `pyproject.toml` за назвою пакета.
+- collectUvDiff — Збирає різницю між поточним `pyproject.toml` і його backup-копією в `cwd`.
+- listDirectDependencies — Повертає прямі залежності з `[project].dependencies` поточного `pyproject.toml` разом з extras.
+
+Конфіги, на які спирається код: package.json
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/skills/taze/js/orchestrate.mjs

@@ -1,12 +1,15 @@
 /** @see ./docs/orchestrate.md */
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
-import { copyFile, rm } from 'node:fs/promises'
+import { copyFile, readFile, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 
+import { parse as parseToml } from 'smol-toml'
+
 import { getMonorepoPackageRootDirs } from '../../../scripts/lib/workspaces.mjs'
 import { collectCargoDiff } from './cargo-diff.mjs'
 import { collectTazeDiff } from './diff.mjs'
+import { collectUvDiff, listDirectDependencies } from './uv-diff.mjs'
 
 /** Суфікс бекапу package.json — той самий, що й у `diff.mjs`/кроці 1 SKILL.md. */
 const BACKUP_SUFFIX = '.taze-bak'
@@ -59,6 +62,30 @@ export function buildCargoDependencyPrompt({ manifest, pkg, from, to }) {
   ].join('\n')
 }
 
+/**
+ * Промпт ОДНОГО ітеративного виклику для Python-пакета — Python/uv-варіант
+ * [`buildDependencyPrompt`] (кроки 4-6 SKILL.md, Python-гілка), для ОДНОГО
+ * major-пакета. Кроки 1-3/7/8 виконує оркестратор детерміновано, без LLM.
+ * @param {{manifest: string, pkg: string, from: string, to: string}} entry запис major-diff (з `collectUvDiff`)
+ * @returns {string} готовий промпт
+ */
+export function buildUvDependencyPrompt({ manifest, pkg, from, to }) {
+  return [
+    '# Major-оновлення одного Python-пакета: перевірка сумісності й рефакторинг',
+    '',
+    `Пакет \`${pkg}\` у \`${manifest}\`: **${from} → ${to}** — вже застосовано (\`uv remove\` + \`uv add --bounds lower\` виконано детерміновано, без тебе). Твоя задача — лише breaking-changes-перевірка й, за потреби, рефакторинг.`,
+    '',
+    '## Кроки',
+    `1. Зібрати breaking changes цього оновлення: CHANGELOG/Releases репозиторію пакета (адреса — зі сторінки https://pypi.org/project/${pkg}/) між ${from} і ${to}.`,
+    `2. Знайти використання зачепленого API в коді проєкту (\`rg -n --type py\` по імпортах/викликах \`${pkg}\`).`,
+    '3. Сумісно — нічого не робити. Несумісно — застосувати міграцію (перейменувати імпорт, оновити сигнатуру виклику, замінити видалений параметр еквівалентом).',
+    '4. Якщо були правки — запусти наявні в проєкті лінт/typecheck/test (`ruff`/`mypy`/`pytest` тощо — залежно від того, що реально налаштовано).',
+    '5. Нетривіальна/неоднозначна міграція — не вгадуй, залиш TODO-коментар із посиланням на CHANGELOG.',
+    '',
+    'У відповіді одним абзацом підсумуй: сумісно / зрефакторено (які файли) / TODO (чому).'
+  ].join('\n')
+}
+
 /**
  * Диспетчер одного ітеративного виклику на обраний раннер. `pi` — вбудований
  * pi-агент (`@7n/llm-lib/agent-skill`; текст перехоплюється через `deps.out`,
@@ -257,6 +284,92 @@ export function findCargoManifests(cwd, deps = {}) {
     .filter(Boolean)
 }
 
+/**
+ * Чи встановлений `uv` — без нього неможливо детерміновано перетнути
+ * major-межу Python-залежностей (SKILL.md §Передумови, Python-гілка).
+ * @param {typeof spawnSync} spawnFn інжект для тестів
+ * @returns {boolean} true — `uv` доступний
+ */
+function hasUv(spawnFn) {
+  return spawnFn('uv', ['--version'], { encoding: 'utf8' }).status === 0
+}
+
+/**
+ * Знаходить кореневий `pyproject.toml` (крок 0.2 SKILL.md, Python-гілка).
+ * v1: один кореневий файл, не per-package, як `find`-обхід для Cargo.toml —
+ * поточна uv-конвенція (single-project, без workspace-обходу).
+ * @param {string} cwd корінь репо
+ * @returns {string[]} `['pyproject.toml']`, якщо файл існує, інакше `[]`
+ */
+export function findPyprojectManifest(cwd) {
+  return existsSync(join(cwd, 'pyproject.toml')) ? ['pyproject.toml'] : []
+}
+
+/**
+ * Бекапить pyproject.toml + uv.lock (крок 1 SKILL.md, Python-гілка) —
+ * потрібно для класифікації major/minor через `collectUvDiff` після bump-у.
+ * @param {string} cwd корінь репо
+ * @param {{ copyFile?: (src: string, dest: string) => Promise<void> }} [deps] інжект
+ * @returns {Promise<void>}
+ */
+export async function backupUvManifest(cwd, deps = {}) {
+  const copy = deps.copyFile ?? copyFile
+  const pyprojectPath = join(cwd, 'pyproject.toml')
+  if (existsSync(pyprojectPath)) await copy(pyprojectPath, `${pyprojectPath}${BACKUP_SUFFIX}`)
+  const lockPath = join(cwd, 'uv.lock')
+  if (existsSync(lockPath)) await copy(lockPath, `${lockPath}${BACKUP_SUFFIX}`)
+}
+
+/**
+ * Прибирає бекапи pyproject.toml/uv.lock після завершення (крок 7 SKILL.md,
+ * Python-гілка).
+ * @param {string} cwd корінь репо
+ * @param {{ rm?: (path: string, opts?: object) => Promise<void> }} [deps] інжект
+ * @returns {Promise<void>}
+ */
+export async function cleanupUvBackups(cwd, deps = {}) {
+  const remove = deps.rm ?? rm
+  await remove(join(cwd, `pyproject.toml${BACKUP_SUFFIX}`), { force: true })
+  await remove(join(cwd, `uv.lock${BACKUP_SUFFIX}`), { force: true })
+}
+
+/**
+ * Піднімає кожну пряму залежність pyproject.toml через `uv remove` + `uv add
+ * <pkg>[extras] --bounds lower` (крок 2 SKILL.md, Python-гілка) — `uv` не
+ * має єдиної команди "підняти все до latest, навіть через major", на
+ * відміну від `bunx taze -w -r latest`/`cargo upgrade --incompatible allow`
+ * (підтверджено емпірично: `uv add <pkg>` на вже присутній залежності —
+ * no-op, specifier НЕ переписується без попереднього `uv remove`). Провал
+ * одного пакета (мережа/резолюція) не втрачає прогрес по інших —
+ * best-effort відновлення оригінального рядка, якщо `uv add` не вдався
+ * після `uv remove`.
+ * @param {string} cwd корінь репо
+ * @param {typeof spawnSync} spawnFn інжект для тестів
+ * @param {(line: string) => void} log колбек прогресу
+ * @param {{ readFile?: (path: string, encoding: string) => Promise<string> }} [deps] інжект
+ * @returns {Promise<void>}
+ */
+async function bumpUvDependencies(cwd, spawnFn, log, deps = {}) {
+  const read = deps.readFile ?? readFile
+  const text = await read(join(cwd, 'pyproject.toml'), 'utf8')
+  const manifest = parseToml(text)
+  const directDeps = listDirectDependencies(manifest)
+
+  for (const dep of directDeps) {
+    const pkgSpec = dep.extras.length > 0 ? `${dep.name}[${dep.extras.join(',')}]` : dep.name
+    const removeResult = spawnFn('uv', ['remove', dep.name], { cwd, encoding: 'utf8' })
+    if (removeResult.status !== 0) {
+      log(`  ⚠️ uv remove ${dep.name}: ${removeResult.stderr || removeResult.stdout}`)
+      continue
+    }
+    const addResult = spawnFn('uv', ['add', pkgSpec, '--bounds', 'lower'], { cwd, encoding: 'utf8' })
+    if (addResult.status !== 0) {
+      log(`  ⚠️ uv add ${pkgSpec}: ${addResult.stderr || addResult.stdout} — відновлюю ${dep.raw}`)
+      spawnFn('uv', ['add', dep.raw], { cwd, encoding: 'utf8' })
+    }
+  }
+}
+
 /**
  * Форматує один рядок результату ітерації (спільний для npm- і Rust-гілки).
  * @param {{pkg: string, ok: boolean, error: string|null, from: string, to: string}} r результат ітерації
@@ -269,6 +382,34 @@ function formatResultLine(r, scopeLabel) {
   return `  ${status} \`${r.pkg}\` (${scopeLabel}): ${r.from} → ${r.to}${errorSuffix}`
 }
 
+/** Пуста гілка-екосистема (для дефолту, коли `rust`/`python` не знайдені взагалі). */
+const EMPTY_ECOSYSTEM = { manifests: [], processed: false, skippedReason: null, minorPatch: 0, results: [] }
+
+/**
+ * Додає секцію звіту однієї не-npm екосистемної гілки (Rust/Python) —
+ * спільна логіка для «Rust-крейти»/«Python-пакети (uv)», обидві мають
+ * ідентичну форму результату ({manifest, pkg, from, to, ok, error}).
+ * @param {string[]} lines масив рядків звіту (мутується)
+ * @param {{manifests:string[], processed:boolean, skippedReason:string|null, minorPatch:number, results:Array<{pkg:string, manifest:string, from:string, to:string, ok:boolean, error:string|null}>}} eco дані гілки
+ * @param {{title: string, manifestNoun: string, skillSection: string}} labels мітки секції
+ * @returns {number} totalChanged цієї гілки
+ */
+function appendEcosystemSection(lines, eco, { title, manifestNoun, skillSection }) {
+  if (eco.manifests.length === 0) return 0
+  lines.push('', `### ${title}`)
+  if (!eco.processed) {
+    lines.push(
+      `- ⏭ Пропущено (${eco.skippedReason}) — ${eco.manifests.length} ${manifestNoun}, онови вручну за ${skillSection}: ${eco.manifests.join(', ')}`
+    )
+    return 0
+  }
+  lines.push(`- **Оновлено (minor/patch):** ${eco.minorPatch}`, `- **Major-оновлення:** ${eco.results.length}`)
+  for (const r of eco.results) {
+    lines.push(formatResultLine(r, r.manifest))
+  }
+  return eco.minorPatch + eco.results.length
+}
+
 /**
  * Компонує підсумковий звіт (крок 8 SKILL.md) детерміновано з результатів
  * ітерацій — без окремого LLM-виклику для самого звіту.
@@ -276,7 +417,14 @@ function formatResultLine(r, scopeLabel) {
  *   minorPatch: number,
  *   totalChanged: number,
  *   results: Array<{pkg:string, workspace:string, from:string, to:string, ok:boolean, error:string|null}>,
- *   rust: {
+ *   rust?: {
+ *     manifests: string[],
+ *     processed: boolean,
+ *     skippedReason: string|null,
+ *     minorPatch: number,
+ *     results: Array<{pkg:string, manifest:string, from:string, to:string, ok:boolean, error:string|null}>
+ *   },
+ *   python?: {
  *     manifests: string[],
  *     processed: boolean,
  *     skippedReason: string|null,
@@ -286,7 +434,7 @@ function formatResultLine(r, scopeLabel) {
  * }} args дані звіту
  * @returns {string} markdown-звіт
  */
-export function formatReport({ minorPatch, totalChanged, results, rust }) {
+export function formatReport({ minorPatch, totalChanged, results, rust = EMPTY_ECOSYSTEM, python = EMPTY_ECOSYSTEM }) {
   const lines = [
     '## taze: підсумок',
     '',
@@ -297,23 +445,18 @@ export function formatReport({ minorPatch, totalChanged, results, rust }) {
     lines.push(formatResultLine(r, r.workspace))
   }
 
-  let rustTotalChanged = 0
-  if (rust.manifests.length > 0) {
-    lines.push('', '### Rust-крейти')
-    if (rust.processed) {
-      lines.push(`- **Оновлено (minor/patch):** ${rust.minorPatch}`, `- **Major-оновлення:** ${rust.results.length}`)
-      for (const r of rust.results) {
-        lines.push(formatResultLine(r, r.manifest))
-      }
-      rustTotalChanged = rust.minorPatch + rust.results.length
-    } else {
-      lines.push(
-        `- ⏭ Пропущено (${rust.skippedReason}) — ${rust.manifests.length} Cargo.toml, онови вручну за Rust-гілкою SKILL.md: ${rust.manifests.join(', ')}`
-      )
-    }
-  }
-
-  lines.push('', `- **Всього змінено:** ${totalChanged + rustTotalChanged}`)
+  const rustTotalChanged = appendEcosystemSection(lines, rust, {
+    title: 'Rust-крейти',
+    manifestNoun: 'Cargo.toml',
+    skillSection: 'Rust-гілкою SKILL.md'
+  })
+  const pythonTotalChanged = appendEcosystemSection(lines, python, {
+    title: 'Python-пакети (uv)',
+    manifestNoun: 'pyproject.toml',
+    skillSection: 'Python-гілкою SKILL.md'
+  })
+
+  lines.push('', `- **Всього змінено:** ${totalChanged + rustTotalChanged + pythonTotalChanged}`)
   return lines.join('\n')
 }
 
@@ -328,9 +471,9 @@ export function formatReport({ minorPatch, totalChanged, results, rust }) {
  *   cwd?: string,
  *   runner?: 'pi' | 'cursor' | 'codex',
  *   log?: (line: string) => void,
- *   deps?: { spawnFn?: typeof spawnSync, collectTazeDiff?: (cwd: string) => Promise<object>, collectCargoDiff?: (cwd: string, manifests: string[]) => Promise<object>, callRunner?: (runner: string, prompt: string, cwd: string, deps: object) => Promise<{ok: boolean, text: string, error: string|null}> } & Record<string, unknown>
+ *   deps?: { spawnFn?: typeof spawnSync, collectTazeDiff?: (cwd: string) => Promise<object>, collectCargoDiff?: (cwd: string, manifests: string[]) => Promise<object>, collectUvDiff?: (cwd: string) => Promise<object>, bumpUvDependencies?: (cwd: string, spawnFn: typeof spawnSync, log: (line: string) => void, deps: object) => Promise<void>, callRunner?: (runner: string, prompt: string, cwd: string, deps: object) => Promise<{ok: boolean, text: string, error: string|null}> } & Record<string, unknown>
  * }} [options] опції + інжекти для тестів
- * @returns {Promise<{ ok: boolean, report: string, results: Array<object>, rustResults: Array<object> }>} результат
+ * @returns {Promise<{ ok: boolean, report: string, results: Array<object>, rustResults: Array<object>, pythonResults: Array<object> }>} результат
  */
 export async function runTazeOrchestrator(options = {}) {
   const cwd = options.cwd ?? process.cwd()
@@ -403,8 +546,51 @@ export async function runTazeOrchestrator(options = {}) {
     }
   }
 
-  const report = formatReport({ minorPatch: diff.minorPatch, totalChanged: diff.totalChanged, results, rust })
+  const pyprojectManifests = findPyprojectManifest(cwd)
+  let python = { manifests: pyprojectManifests, processed: false, skippedReason: null, minorPatch: 0, results: [] }
+
+  if (pyprojectManifests.length > 0 && !hasUv(spawnFn)) {
+    python.skippedReason = '`uv` не встановлено (https://docs.astral.sh/uv/getting-started/installation/)'
+    log(`⏭ Python: ${python.skippedReason}`)
+  } else if (pyprojectManifests.length > 0) {
+    log('📦 Бекап pyproject.toml/uv.lock...')
+    await backupUvManifest(cwd, deps)
+
+    log('⬆️  uv remove + uv add --bounds lower (по кожній прямій залежності)...')
+    const bump = deps.bumpUvDependencies ?? bumpUvDependencies
+    await bump(cwd, spawnFn, log, deps)
+
+    const collectUv = deps.collectUvDiff ?? collectUvDiff
+    const uvDiff = await collectUv(cwd)
+    log(`🔍 Python diff: ${uvDiff.major.length} major, ${uvDiff.minorPatch} minor/patch`)
+
+    const pythonResults = []
+    for (const entry of uvDiff.major) {
+      log(`🔧 [python] ${entry.pkg} (${entry.manifest}): ${entry.from} → ${entry.to}...`)
+      const outcome = await call(runner, buildUvDependencyPrompt(entry), cwd, deps)
+      pythonResults.push({ ...entry, ...outcome })
+      log(outcome.ok ? `  ✅ ${entry.pkg}` : `  ❌ ${entry.pkg}: ${outcome.error}`)
+    }
+
+    await cleanupUvBackups(cwd, deps)
+
+    python = {
+      manifests: pyprojectManifests,
+      processed: true,
+      skippedReason: null,
+      minorPatch: uvDiff.minorPatch,
+      results: pythonResults
+    }
+  }
+
+  const report = formatReport({ minorPatch: diff.minorPatch, totalChanged: diff.totalChanged, results, rust, python })
   log(report)
 
-  return { ok: results.every(r => r.ok) && rust.results.every(r => r.ok), report, results, rustResults: rust.results }
+  return {
+    ok: results.every(r => r.ok) && rust.results.every(r => r.ok) && python.results.every(r => r.ok),
+    report,
+    results,
+    rustResults: rust.results,
+    pythonResults: python.results
+  }
 }

package/skills/taze/js/uv-diff.mjs

@@ -0,0 +1,176 @@
+/** @see ./docs/uv-diff.md */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { parse as parseToml } from 'smol-toml'
+
+import { isBreaking } from './diff.mjs'
+
+/** Дефолтний суфікс бекапу — той самий, що й для package.json/Cargo.toml. */
+const DEFAULT_BACKUP_SUFFIX = '.taze-bak'
+
+// Ім'я пакета (PEP 508: літери/цифри/`._-`) + опційні `[extras]` + решта
+// (версійний specifier, можливо з `; marker` — ігнорується, не наш скоуп).
+const PEP508_RE = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*])?\s*([^;]*)/
+
+/**
+ * Парсить один PEP 508-рядок залежності (`"typer>=0.19.1,<0.20.0"`,
+ * `"strawberry-graphql[asgi]>=0.282.0"`) на ім'я/extras/specifier.
+ * @param {string} requirement рядок із `[project].dependencies`
+ * @returns {{name: string, extras: string[], specifier: string}|null} розбір, або null для невалідного рядка
+ */
+export function parsePep508(requirement) {
+  if (typeof requirement !== 'string') return null
+  const m = PEP508_RE.exec(requirement)
+  if (!m) return null
+  const extras = m[2]
+    ? m[2]
+        .slice(1, -1)
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean)
+    : []
+  return { name: m[1], extras, specifier: (m[3] ?? '').trim() }
+}
+
+// 1-3 числові компоненти PEP 440 (`"1"`, `"0.4"`, `"1.2.3"`), без урахування
+// pre/post/dev-суфіксів (поза скоупом major/minor/patch-класифікації).
+const PEP440_VERSION_RE = /^[\s=><~!]*(\d+)(?:\.(\d+))?(?:\.(\d+))?/
+// Операторний префікс версійного сегмента (`>=`, `==`, `~=`, `!=` тощо) — для відсікання при витягуванні голої версії.
+const VERSION_OPERATOR_PREFIX_RE = /^[>=~!]+/
+
+/**
+ * Парсить ядро PEP 440-версії (major.minor.patch, відсутні компоненти → 0).
+ * @param {string} spec версійний рядок (сегмент specifier-а, без операторного префікса)
+ * @returns {{major:number, minor:number, patch:number}|null} ядро або null для не-версії
+ */
+export function parsePep440Version(spec) {
+  if (typeof spec !== 'string') return null
+  const m = PEP440_VERSION_RE.exec(spec)
+  if (!m) return null
+  return { major: Number(m[1]), minor: Number(m[2] ?? 0), patch: Number(m[3] ?? 0) }
+}
+
+/**
+ * Дістає нижню межу версійного specifier-а (перший сегмент `>=`/`==`/`~=`
+ * серед comma-separated списку, напр. `">=0.19.1,<0.20.0"` → `"0.19.1"`).
+ * Саме нижня межа відповідає версії, яку реально ставить `uv add --bounds lower`.
+ * @param {string} specifier версійний specifier із `parsePep508`
+ * @returns {string|null} версія нижньої межі, або null якщо немає жодного `>=`/`==`/`~=`-сегмента
+ */
+export function extractLowerBoundVersion(specifier) {
+  if (!specifier) return null
+  const clause = specifier
+    .split(',')
+    .map(s => s.trim())
+    .find(c => c.startsWith('>=') || c.startsWith('==') || c.startsWith('~='))
+  return clause ? clause.replace(VERSION_OPERATOR_PREFIX_RE, '').trim() : null
+}
+
+/**
+ * Порівнює `[project].dependencies` двох pyproject.toml — той самий контракт,
+ * що й `diffPackageJson`/`diffCargoToml`. Матчинг по ІМЕНІ пакета (не по
+ * позиції в масиві — PEP 621 `dependencies` це список PEP 508-рядків, не
+ * мапа ім'я→версія).
+ * @param {object} oldManifest розпарсений старий pyproject.toml (бекап)
+ * @param {object} newManifest розпарсений новий pyproject.toml
+ * @param {string} manifest відносний шлях pyproject.toml (мітка джерела запису)
+ * @returns {{major: Array<{manifest:string, pkg:string, from:string, to:string}>, minorPatch:number}} зміни
+ */
+export function diffPyprojectDeps(oldManifest, newManifest, manifest) {
+  const oldDeps = oldManifest?.project?.dependencies ?? []
+  const newByName = new Map()
+  for (const requirement of newDeps(newManifest)) {
+    const parsed = parsePep508(requirement)
+    if (parsed) newByName.set(parsed.name, parsed)
+  }
+
+  const major = []
+  let minorPatch = 0
+  for (const oldRequirement of oldDeps) {
+    const oldParsed = parsePep508(oldRequirement)
+    if (!oldParsed) continue
+    const newParsed = newByName.get(oldParsed.name)
+    if (!newParsed || newParsed.specifier === oldParsed.specifier) continue
+
+    const from = extractLowerBoundVersion(oldParsed.specifier)
+    const to = extractLowerBoundVersion(newParsed.specifier)
+    if (from === null || to === null || from === to) continue
+
+    const fromV = parsePep440Version(from)
+    const toV = parsePep440Version(to)
+    if (fromV && toV && isBreaking(fromV, toV)) {
+      major.push({ manifest, pkg: oldParsed.name, from, to })
+    } else {
+      minorPatch += 1
+    }
+  }
+  return { major, minorPatch }
+}
+
+/**
+ * @param {object} manifest розпарсений pyproject.toml
+ * @returns {string[]} `[project].dependencies` (порожній масив, якщо відсутнє)
+ */
+function newDeps(manifest) {
+  return manifest?.project?.dependencies ?? []
+}
+
+/**
+ * Читає й парсить TOML-файл, або повертає null, якщо файл відсутній/невалідний.
+ * @param {string} path абсолютний шлях
+ * @returns {Promise<object|null>} розпарсений обʼєкт або null
+ */
+async function readTomlOrNull(path) {
+  if (!existsSync(path)) return null
+  try {
+    return parseToml(await readFile(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Збирає diff по pyproject.toml: порівнює `<cwd>/pyproject.toml` з
+ * `<cwd>/pyproject.toml<backupSuffix>` — той самий контракт, що й
+ * `collectTazeDiff`/`collectCargoDiff`.
+ * @param {string} cwd корінь репозиторію (де лежить pyproject.toml — uv-конвенція: один кореневий файл, не per-crate, як Cargo.toml)
+ * @param {string} [backupSuffix] суфікс бекап-файлу
+ * @returns {Promise<{major: Array<{manifest:string, pkg:string, from:string, to:string}>, minorPatch:number, totalChanged:number, comparedManifests:number}>} агрегований diff
+ */
+export async function collectUvDiff(cwd, backupSuffix = DEFAULT_BACKUP_SUFFIX) {
+  const oldManifest = await readTomlOrNull(join(cwd, `pyproject.toml${backupSuffix}`))
+  const newManifest = await readTomlOrNull(join(cwd, 'pyproject.toml'))
+  if (!oldManifest || !newManifest) {
+    return { major: [], minorPatch: 0, totalChanged: 0, comparedManifests: 0 }
+  }
+  const res = diffPyprojectDeps(oldManifest, newManifest, 'pyproject.toml')
+  return {
+    major: res.major,
+    minorPatch: res.minorPatch,
+    totalChanged: res.major.length + res.minorPatch,
+    comparedManifests: 1
+  }
+}
+
+/**
+ * Дістає `{name, extras, raw}` кожної прямої залежності з
+ * `[project].dependencies` поточного pyproject.toml — вхід для
+ * per-пакетного bump-циклу (`uv` немає єдиної команди "підняти все до
+ * latest, навіть через major", на відміну від `bunx taze -w -r latest`/
+ * `cargo upgrade --incompatible allow` — підтверджено емпірично: `uv add
+ * <pkg>` на вже присутній залежності НЕ переписує specifier, поки не буде
+ * `uv remove` спершу). `raw` — оригінальний PEP 508-рядок, потрібен для
+ * best-effort відновлення, якщо `uv add` після `uv remove` не вдався.
+ * @param {object} manifest розпарсений pyproject.toml
+ * @returns {Array<{name: string, extras: string[], raw: string}>} прямі залежності
+ */
+export function listDirectDependencies(manifest) {
+  return newDeps(manifest)
+    .map(requirement => {
+      const parsed = parsePep508(requirement)
+      return parsed ? { ...parsed, raw: requirement } : null
+    })
+    .filter(Boolean)
+    .map(({ name, extras, raw }) => ({ name, extras, raw }))
+}