@nitra/cursor 5.3.3 → 5.4.0

package/scripts/docs/sync-claude-config.md

@@ -1,52 +1,112 @@
+---
+docgen:
+  source: npm/scripts/sync-claude-config.mjs
+  crc: ad7b8440
+  score: 95
+---
+
 # sync-claude-config.mjs
 
 ## Огляд
 
-Цей файл синхронізує конфігурацію Claude Code з шаблонів пакету `npm/.claude-template`, включаючи налаштування, slash-команди та хуки. Він забезпечує узгодженість між проєктом та базовою конфігурацією, автоматично оновлюючи та підтримуючи налаштування хуків та команд. Це дозволяє використовувати стандартні налаштування та автоматично адаптувати проєкт до змін у шаблоні.
+Файл синхронізує конфігурацію Claude Code (`.claude/settings.json`), slash-команди з темплейту та Cursor hooks (`.cursor/hooks.json`) у поточний проєкт з використанням темплейтів пакету `npm/.claude-template/`. Він виконує злиття користувацьких полів, дозволів та хуків з різних джерел. Синхронізуються та видаляються залежні скрипти та фрагменти конфігурації.
 
 ## Поведінка
 
-- `parseGitignoreFragmentLines`: Розбиває рядок фрагменту `.gitignore` на окремі рядки, видаляє порожні та коментарні рядки.
-- `syncGitignoreAdrFragment`: Дописує відсутні рядки з канонічного фрагменту `.gitignore` у `.gitignore` проєкту.
-- `syncClaudeCommands`: Копіює slash-команди з `commands/` темплейту в `.claude/commands/*.md`.
-- `syncClaudeSettings`: Об'єднує конфігурацію Claude Code з темплейту, зберігаючи користувацькі налаштування та перезаписуючи хуки, що ідентифікуються маркерами.
-- `syncCursorHooksConfig`: Об'єднує конфігурацію хуків Cursor з темплейту, додаючи або видаляючи хуки ADR Stop-hook залежно від наявності правила `adr`.
-- `syncAdrHookScript`: Копіює bash-скрипт ADR capture Stop-hook з темплейту в `.claude/hooks/capture-decisions.sh`.
-- `syncAdrNormalizeHookScript`: Копіює bash-скрипт ADR normalize Stop-hook з темплейту в `.claude/hooks/normalize-decisions.sh`.
-- `syncAdrHookLibScripts`: Копіює bash-скрипти lib-файлів з `commands/` темплейту в `.claude/hooks/lib/`.
-- `removeOrphanAdrHookLib`: Видаляє директорію lib-файлів з `.claude/hooks/lib/`, якщо правило `adr` вимкнено.
-- `syncPiExtensions`: Копіює розширення TypeScript з `npm/.pi-template/extensions/n-cursor-adr/` в `.pi/extensions/n-cursor-adr/`.
-- `removeOrphanPiExtension`: Видаляє директорію розширення TypeScript з `.pi/extensions/n-cursor-adr/`, якщо правило `adr` вимкнено.
-- `syncClaudeConfig`: Синхронізує конфігурацію Claude Code та Cursor hooks, об'єднуючи їх та додаючи/видаляючи хуки
+MANAGED_HOOK_COMMAND_MARKER Маркер PostToolUse fix-hook
 
-## Публічний API
+DOC_FILES_HOOK_COMMAND_MARKER Маркер doc-files staleness-hook
 
-- MANAGED_HOOK_COMMAND_MARKER — Маркер для фіксації хуків PostToolUse.
-- LEGACY_STOP_HOOK_COMMAND_MARKER — Маркер для legacy-хуків Stop, використовується під час оновлення.
-- ADR_HOOK_COMMAND_MARKER — Маркер для хуків ADR Stop, визначає шлях до скрипту capture-decisions.
-- ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для хуків ADR Stop, визначає шлях до скрипту normalize-decisions.
-- CURSOR_ADR_HOOK_COMMAND_MARKER — Маркер для хуків Cursor ADR Stop, шлях до скрипту в `.cursor/hooks.json`.
-- CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для хуків Cursor ADR Normalize Stop, шлях до скрипту в `.cursor/hooks.json`.
-- MANAGED_HOOK_COMMAND_MARKERS — Усі маркери managed-хуків пакета.
-- PI_DIR — Корінь артефактів pi.dev у проєкті-споживачі.
-- PI_EXTENSIONS_DIR — Директорія pi.dev TS-extensions у проєкті-споживачі.
-- PI_TEMPLATE_DIR_NAME — Назва bundled-директорії pi-template у пакеті `@nitra/cursor`.
-- PI_EXTENSION_NAME — Ім'
+LEGACY_STOP_HOOK_COMMAND_MARKER Маркер старого Stop-hook
 
-## Гарантії поведінки
+ADR_HOOK_COMMAND_MARKER Маркер ADR Stop-hook
+
+ADR_NORMALIZE_HOOK_COMMAND_MARKER Маркер ADR Stop-hook
+
+CURSOR_ADR_HOOK_COMMAND_MARKER Маркер Cursor ADR Stop-hook
+
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER Маркер Cursor ADR Normalize Stop-hook
+
+MANAGED_HOOK_COMMAND_MARKERS Маркерів для відрізнення managed-hook'ів
+
+PI_DIR Корінь pi.dev артефактів
+
+PI_EXTENSIONS_DIR Директорія pi.dev TS-extensions
+
+PI_TEMPLATE_DIR_NAME Назва bundled-директорії pi-template
+
+PI_EXTENSION_NAME Імʼя bundled pi-extension'а
+
+ADR_GITIGNORE_SNIPPET_REL Відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів
+
+mergeAllowList Зливає список allow-permissions без дублікатів
 
-Немає кешування.
+mergeHooks Зливає hooks-секцію, видаляючи managed-групи з існуючої конфігурації
 
-Функція повертає `true`, якщо синхронізація завершилася успішно.
+mergeSettings Зливає конфігурацію Claude, перевіряючи та зливаючи permissions та hooks
 
-Якщо `claude-config` встановлено на `false` у `.n-cursor.json`, функція не змінює конфігурацію Claude.
+mergeCursorHooksConfig Зливає конфігурацію Cursor, керуючи додаванням/видаленням ADR stop entries
 
-`settings.json` оновлюється шляхом об'єднання конфігурації з `.claude-template/settings.json`, де перекриваються команди, що містять `MANAGED_HOOK_COMMAND_MARKER`, дозволи `permissions.allow` об'єднуються, і правила `adr` додаються/видаляються згідно з їх статусом у `.n-cursor.json`.
+syncCursorHooksConfig Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks
 
-`.claude/commands/*.md` оновлюється шляхом повного заміщення вмісту з `.claude-template/commands/`.
+syncClaudeSettings Синхронізує `.claude/settings.json` за темплейтом
 
-`.claude/hooks/capture-decisions.sh` оновлюється шляхом повного копіювання з `.claude-template/hooks/` лише тоді, коли правило `adr` увімкнено в `.n-cursor.json`.
+syncAdrHookScript Копіює канонічний bash-скрипт ADR capture Stop-hook з темплейту
 
-`.claude/hooks/normalize-decisions.sh` оновлюється шляхом повного копіюювання з `.claude-template/hooks/` лише тоді, коли правило `adr` увімкнено в `.n-cursor.json`.
+syncAdrNormalizeHookScript Копіює канонічний bash-скрипт ADR normalize Stop-hook з темплейту
+
+syncAdrHookLibScripts Копіює `.sh`-файли з `.claude-template/hooks/lib/` у `.claude/hooks/`
+
+removeOrphanAdrHookLib Видаляє директорію `.claude/hooks/lib/` з проєкту-споживача
+
+syncPiExtensions Копіює bundled pi.dev TS-extension з пакета у проєкт
+
+removeOrphanPiExtension Видаляє директорію `.pi/extensions/n-cursor-adr/` з проєкту-споживача
+
+syncGitignoreAdrFragment Дописує відсутні рядки з канонічного ADR-фрагмента до кореневого `.gitignore` проєкту
+
+syncClaudeCommands Копіює slash-команди з `commands/` темплейту у `.claude/commands/`
+
+syncClaudeConfig Виконує повну синхронізацію Claude Code-конфігу з темплейту
+
+## Публічний API
+
+MANAGED_HOOK_COMMAND_MARKER — Маркер для хуків PostToolUse fix-hook'а (`npx --no @nitra/cursor post-tool-use-fix`).
+DOC_FILES_HOOK_COMMAND_MARKER — Маркер для хуків doc-files staleness-hook'ів (PostToolUse `--hook` та Stop-гейт `--git`).
+LEGACY_STOP_HOOK_COMMAND_MARKER — Маркер для старого Stop-hook'а — для очищення при оновленні існуючих інсталяцій.
+ADR_HOOK_COMMAND_MARKER — Маркер для ADR Stop-hook'а — підрядок шляху до bash-скрипта capture-decisions.sh.
+ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для ADR Stop-hook'а — підрядок шляху до bash-скрипта normalize-decisions.sh.
+CURSOR_ADR_HOOK_COMMAND_MARKER — Маркер для Cursor ADR Stop-hook'а — той самий script path, але в `.cursor/hooks.json`.
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Маркер для Cursor ADR Stop-hook'а — той самий script path, але в `.cursor/hooks.json`.
+MANAGED_HOOK_COMMAND_MARKERS — Група маркерів managed-hook'ів пакета — відрізняються від користувацьких.
+Legacy stop-hook включений сюди, щоб старі entries автоматично видалялись при наступному sync-у.
+PI_DIR — Корінь артефактів pi.dev у проєкті-споживачі.
+PI_EXTENSIONS_DIR — Директорія TS-розширень pi.dev у проєкті-споживачі.
+PI_TEMPLATE_DIR_NAME — Назва bundled-директорії pi-template у пакеті `@nitra/cursor`.
+PI_EXTENSION_NAME — Імʼя bundled pi-extension'а для ADR capture/normalize.
+ADR_GITIGNORE_SNIPPET_REL — Відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета.
+mergeAllowList — Зливає список allow-permissions: об'єднує існуючі та темплейтні дозволи без дублікатів, зберігаючи користувацький порядок.
+mergeHooks — Зливає hooks-секцію. Видаляє managed-групи з існуючої конфігурації та дописує managed-групи з темплейту. Перебір подій union-у враховує зміну порядку хуків.
+mergeSettings — Повертає об'єднаний об'єкт settings.json.
+mergeCursorHooksConfig — Зливає `.cursor/hooks.json`: користувацькі записи зберігаються, managed ADR записи в `hooks.stop` перезаписуються або видаляються залежно від `includeAdrHook`.
+syncCursorHooksConfig — Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks. Cursor читає project-level config з `.cursor/hooks.json`; хук-скрипти залишаються спільними з Claude Code у `.claude/hooks/`.
+syncClaudeSettings — Синхронізує `.claude/settings.json` за темплейтом, зберігаючи решту користувацьких полів.
+syncAdrHookScript — Копіює канонічний `.claude/hooks/capture-decisions.sh` з темплейту пакета.
+syncAdrNormalizeHookScript — Копіює канонічний `.claude/hooks/normalize-decisions.sh` з темплейту пакета.
+syncAdrHookLibScripts — Копіює всі `.sh`-файли з `.claude-template/hooks/lib/` у `.claude/hooks/lib/` проєкту.
+Файли source-only (без exec bit) — їх source-ять capture/normalize-decisions.sh, щоб уникнути дублювання спільної bash-логіки (`is_tooling_only_change`, `git_diff_only_version_field`).
+Тека fully-owned — при кожному sync-у перезаписується.
+removeOrphanAdrHookLib — Видаляє директорію `.claude/hooks/lib/` з проєкту-споживача. Викликається, коли правило `adr` вимкнено — бібліотечні файли не самостійні, і їх не потрібні.
+syncPiExtensions — Копіює bundled pi.dev TS-extension `npm/.pi-template/extensions/n-cursor-adr/` (всі файли — `index.ts`, `tsconfig.json`, потенційні `package.json`/`.gitignore` тощо`) у `.pi/extensions/n-cursor-adr/` проєкту-споживача. Тека fully-owned: при кожному sync-у перезаписується. Якщо bundled template відсутній (legacy-версії пакета без `.pi-template/`) або в ньому немає `index.ts` — повертається `{written: false}` без помилки.
+Розширення поверх `index.ts` (tsconfig тощо) потрібні, бо `.pi/extensions/` синхронізується як у проєкти-споживачі, а IDE/TS-сервер мусить резолвити `node:*` модулі без додаткових project-wide конфігів.
+removeOrphanPiExtension — Видаляє директорію `.pi/extensions/n-cursor-adr/` з проєкту-споживача. Викликається, коли правило `adr` вимкнено у `.n-cursor.json` — бібліотечні файли не самостійні, і їх не потрібні (симетрично до cleanup-у `.claude/hooks/{capture,normalize}-decisions.sh`).
+syncGitignoreAdrFragment — Дописує в кореневий `.gitignore` проєкту відсутні рядки з канонічного ADR-фрагмента.
+syncClaudeCommands — Копіює всі slash-команди з `templateDir/commands/` у `.claude/commands/`. Команди ідентифікуються тим, що вони лежать у темплейті — не перетинаються з командами скілів (n-fix, n-lint, ...).
+syncClaudeConfig — Виконує повну синхронізацію Claude Code-конфігу з темплейту пакету в проєкт. Використовується з `bin/n-cursor.js` після інших синків.
+
+## Гарантії поведінки
 
-`.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Свідомо пропускає шляхи: `.git`.
+- Не звертається до мережі.

package/scripts/docs/worktree-cli.md

@@ -1,52 +1,29 @@
 ---
 docgen:
   source: npm/scripts/worktree-cli.mjs
-  crc: 92deb344
+  crc: 4fb54376
+  score: 100
 ---
 
 # worktree-cli.mjs
 
 ## Огляд
 
-Файл `n-cursor worktree` є CLI-оркестратором для управління git worktree. Він дозволяє додавати, видаляти та перевіряти worktree, забезпечуючи зручний інтерфейс для роботи з декількома гілками в одному репозиторії. Цей інструмент використовується для організації робочого процесу розробника, що працює з кількома гілками.
+Файл є CLI-оркестратором `worktree-tool` для керування конвенцією `.worktrees/`. Він забезпечує виконання Git-операцій для додавання, видалення, перегляду та прибирання робочих просторів.
 
 ## Поведінка
 
-1.  **Ініціалізація:** Отримує аргументи командного рядка, включаючи підкоманду та її параметри. Визначає поточний робочий каталог, якщо його не вказано. Ініціалізує контекст для логування та отримання дати.
-2.  **Розбір підкоманди:** Визначає, яку підкоманду було передано. Залежно від підкоманди, виконує відповідні дії.
-3.  **`add` (Створення нового worktree):**
-    - Перевіряє наявність необхідних параметрів: назви гілки та опису.
-    - Визначає унікальну назву гілки, якщо вона вже існує.
-    - Створює новий worktree, використовуючи вказану гілку та опис. Записує опис у файл `.md` у каталозі `.worktrees/`.
-    - Створює нагадування про незакомічені зміни основного дерева, якщо це необхідно.
-4.  **`remove` (Видалення worktree):**
-    - Перевіряє наявність необхідного параметра: назви гілки.
-    - Видаляє checkout та файл `.md` для вказаної гілки.
-    - Видаляє всі осиротілі файли опису, які залишилися після видалення гілки.
-    - Не створює і не обслуговує окремі sibling runtime-файли.
-5.  **`list` (Перелік worktree):**
-    - Виводить список всіх створених worktree, отриманий за допомогою команди `git worktree list`.
-    - Для кожного worktree виводить його повний шлях та вміст файлу опису `.md`.
-6.  **`prune` (Видалення осиротілих worktree):**
-    - Визначає всі файли опису `.md`, які більше не пов'язані з жодною зареєстрованою гілкою worktree.
-    - Видаляє ці осиротілі файли опису.
-7.  \*\*Викона
+1.  Запуск підкоманди add. Перевіряється наявність необхідного імені гілки та опису. Перевіряється унікальність назви для створення нового worktree. Збирається нагадування про незакомічені зміни основного дерева. Виконується git команда для створення worktree. Якщо команда не успішна, повертається помилка. Створюється та записується опис у файлі `.worktrees/`. Повертається код виходу.
+2.  Запуск підкоманди remove. Перевіряється наявність імені гілки. Перевіряється наявність необхідного імені гілки. Визначається шлях до worktree. Виконується git команда для видалення checkout. Якщо команда не успішна, повертається помилка. Якщо вказано прапорець --force, використовується примусовий режим. Видаляється відповідний файл опису. Повертається код виходу.
+3.  Запуск підкоманди list. Виконується git команда для отримання списку worktree. Виводиться результат. Для кожного зареєстрованого файлу опису з директорії `.worktrees/` зчитується вміст файлу та виводиться. Повертається код виходу.
+4.  Запуск підкоманди prune. Виконується git команда для прибирання worktree. Визначається список осиротілих файлів опису. Виконується git команда для прибирання worktree. Для кожного осиротілого файлу опису видаляється відповідний файл. Повертається код виходу.
 
 ## Публічний API
 
-runWorktreeCli — Запускає підкоманду worktree.
+runWorktreeCli — Запускає команду для роботи з підкомандою worktree.
 
 ## Гарантії поведінки
 
-- `runWorktreeCli` повертає `false` при будь-якій помилці.
-- `runWorktreeCli` повертає `null` при помилці, якщо результат неможливо визначити.
-- Немає кешування.
-- `add <branch> "<опис>"` створює гілку `worktree` з описом.
-- `remove <branch> [--force]` видаляє checkout гілки `worktree`, але не видаляє саму гілку.
-- `list` виводить список всіх `worktree`.
-- `prune` видаляє `worktree` без checkout.
-- Немає гарантій щодо стану git-репозиторію.
-- Немає гарантій щодо наявності незакомічених змін.
-- Немає гарантій щодо наявності осиротілих `worktree`.
-- `runWorktreeCli` не кидає винятків.
-- Помилки переховуються.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/scripts/lib/docs/assert-project-root.md

@@ -1,34 +1,32 @@
 ---
 docgen:
   source: npm/scripts/lib/assert-project-root.mjs
-  crc: 3ad7981a
+  crc: adb87c16
+  score: 100
 ---
 
 # assert-project-root.mjs
 
 ## Огляд
 
-Файл забезпечує захист від непередбачуваної поведінки при запуску `npx @nitra/cursor` з піддиректорій git-репозиторію. Він гарантує, що процес синхронізації та встановлення артефактів виконується лише з кореневої директорії проєкту, запобігаючи розповсюдженню конфігураційних файлів у невідповідні місця. Це забезпечує узгодженість та передбачуваність процесу налаштування проєкту.
+Файл перевіряє розташування поточного каталогу відносно кореня git-репозиторію. Функції надають доступ до шляху кореня репозиторію та перевірку, чи знаходиться поточний каталог саме в цьому корені. Код спирається на конфіги, визначені у `.n-cursor.json`.
 
 ## Поведінка
 
-gitToplevel: Визначає реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає `null`, якщо `git` недоступний або не вдалося визначити корінь.
-safeRealpath: Повертає реальний шлях вказаного каталогу, ігноруючи символічні посилання. Якщо шлях не існує, повертає вихідний шлях без змін.
-assertCwdIsProjectRoot: Перевіряє, чи поточний робочий каталог є коренем git-репозиторію. Якщо так, функція не робить нічого. Якщо каталог знаходиться всередині git-репозиторію, але не є його коренем, викидає помилку, що інформує про необхідність перейти в корінь репозиторію.
+gitToplevel
+Повертає абсолютний шлях до кореня git-репозиторію або null, якщо git недоступний або не повертає кореня.
+
+assertCwdIsProjectRoot
+Перевіряє, чи знаходиться поточний каталог у корені git-репозиторію. Кидає помилку, якщо каталог знаходиться всередині репозиторію, але не в корені. Пропускає перевірку, якщо git не знаходить кореня.
 
 ## Публічний API
 
-- gitToplevel — Отримує реальний шлях кореня git-репозиторію, використовуючи `git rev-parse --show-toplevel`. Повертає шлях або `null`, якщо `dir` не є коренем репозиторію або `git` недоступний.
-- assertCwdIsProjectRoot — Перевіряє, чи `dir` є коренем git-репозиторію. Якщо `dir` є піддиректорією репозиторію або знаходиться поза репозиторієм (без визначення `toplevel`), то функція пропускає операцію без помилки.
+- gitToplevel — повертає шлях до кореня git-репозиторію через `git rev-parse --show-toplevel`. Повертає `null`, якщо `dir` не є частиною git-репозиторію або `git` недоступний.
+- assertCwdIsProjectRoot — генерує помилку, якщо `dir` знаходиться у піддиректорії git-репозиторію. Пропускає, якщо `toplevel` відсутній (наприклад, у `git-worktree`), дозволяючи запуск.
 
 ## Гарантії поведінки
 
-- При запуску `npx @nitra/cursor` з кореня будь-якого git-репозиторію, виконується синхронізація проєкту.
-- При запуску `npx @nitra/cursor` з піддиректорії git-репозиторію, `cwd` встановлюється на корінь git-репозиторію.
-- Синхронізація проєкту включає створення та запуск сценаріїв для `.cursor/rules/`, `.cursor/skills/`, `.claude/`, `AGENTS.md`, `CLAUDE.md`, `.n-cursor.json`, `.gitignore`.
-- Синхронізація проєкту включає запуск `bun install`.
-- При невдачі синхронізації повертається `false` або `null`.
-- Немає кешування.
-- Не перехоплює винятки.
-- Функція `gitToplevel` забезпечує доступ до кореня git-репозиторію.
-- Функція `assertCwdIsProjectRoot` перевіряє, чи поточний `cwd` є коренем git-репозиторію.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

package/scripts/lib/docs/changed-files.md

@@ -1,149 +1,34 @@
+---
+docgen:
+  source: npm/scripts/lib/changed-files.mjs
+  crc: 8148d84e
+  score: 100
+---
+
 # changed-files.mjs
 
 ## Огляд
 
-Модуль `changed-files.mjs` — допоміжна бібліотека для збору переліку змінених файлів у робочому дереві git-репозиторію. Використовується lint-оркестратором у quick-режимі та `coverage --changed` для визначення scope-у файлів, на яких потрібно прогнати перевірки.
-
-Логіка модуля:
-
-- збирає tracked-modified та staged файли через `git diff` (з `--diff-filter=ACMR`, тобто Added/Copied/Modified/Renamed — без Deleted);
-- додає untracked файли через `git ls-files --others --exclude-standard` (з повагою до `.gitignore`);
-- дедуплікує об'єднаний список через `Set`;
-- повертає relative-posix шляхи відносно `cwd`;
-- поза git-репо або при помилці git мовчки повертає порожній список (для `gitLines`);
-- для режиму "since base" — fail-closed: якщо базовий комміт недосяжний, кидає явну помилку, щоб gate не пройшов мовчки.
-
-Видалені файли свідомо не включаються — лінтити неіснуючий файл немає сенсу.
-
-## Експорти / API
-
-Модуль експортує дві функції:
-
-| Експорт                    | Тип                                                | Призначення                                                                                                                  |
-| -------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `collectChangedFiles`      | `(cwd?: string) => string[]`                       | Список змінених + untracked файлів робочого дерева відносно `HEAD`.                                                          |
-| `collectChangedFilesSince` | `(base: string \| null, cwd?: string) => string[]` | Список змінених + untracked файлів **відносно довільного базового комміту**. Без `base` — fallback на `collectChangedFiles`. |
-
-Внутрішня (неекспортована) функція:
-
-| Внутрішнє  | Тип                                         | Призначення                                                                                    |
-| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `gitLines` | `(args: string[], cwd: string) => string[]` | Виконує `git <args>` у `cwd` і повертає непорожні trim-нуті рядки stdout або `[]` при помилці. |
-
-## Функції
-
-### `gitLines(args, cwd)` (internal)
-
-Виклик git-команди з парсингом stdout у масив рядків.
-
-- **Сигнатура:** `function gitLines(args: string[], cwd: string): string[]`
-- **Параметри:**
-  - `args` — масив аргументів для `git` (наприклад `['diff', 'HEAD', '--name-only']`).
-  - `cwd` — робоча директорія для процесу `git`.
-- **Повертає:** масив непорожніх рядків stdout (після `trim`). Якщо `r.status !== 0` або є `r.error` — повертає `[]`.
-- **Side effects:**
-  - Синхронно спавнить процес `git` через `spawnSync` з `node:child_process`;
-  - не пише в stdout/stderr батьківського процесу (всі потоки збираються через `encoding: 'utf8'`);
-  - не кидає винятків — fail-silent.
-
-### `collectChangedFiles(cwd?)`
-
-Збирає список змінених + untracked файлів робочого дерева відносно `HEAD`.
-
-- **Сигнатура:** `function collectChangedFiles(cwd?: string): string[]`
-- **Параметри:**
-  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
-- **Алгоритм:**
-  1. `git diff HEAD --name-only --diff-filter=ACMR` — повертає всі tracked файли, які відрізняються від `HEAD` (staged + unstaged), фільтр `ACMR` відсікає Deleted.
-  2. `git ls-files --others --exclude-standard` — повертає untracked файли, які не ігноруються `.gitignore`.
-  3. Об'єднання обох списків через `new Set([...modified, ...untracked])` для дедуплікації.
-- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
-- **Поведінка поза git-репо / при помилці:** `gitLines` мовчки повертає `[]` для обох викликів, тож результат — порожній масив.
-
-### `collectChangedFilesSince(base, cwd?)`
-
-Збирає список змінених + untracked файлів відносно довільного базового комміту. Призначено для сценаріїв, де базовий комміт зафіксовано у стані flow-турнікета (executor комітить кожен крок, тож потрібно ловити зміни «від base», а не «від HEAD»).
-
-- **Сигнатура:** `function collectChangedFilesSince(base: string | null, cwd?: string): string[]`
-- **Параметри:**
-  - `base` — SHA/ref базового комміту (типово `metadata.base_commit` зі стану flow). Якщо `null`/`undefined`/порожній — fallback на `collectChangedFiles(cwd)`.
-  - `cwd` (опційно, дефолт `process.cwd()`) — корінь git-репо.
-- **Алгоритм:**
-  1. Якщо `base` falsy — повертає результат `collectChangedFiles(cwd)`.
-  2. Перевіряє досяжність base через `git rev-parse --verify --quiet <base>^{commit}`.
-  3. Якщо verify не успішний (`status !== 0` або `error`) — **кидає `Error`** з повідомленням: `collectChangedFilesSince: base-комміт «<base>» недосяжний у <cwd> (rebase/force-update?) — coverage --changed не може визначити scope`.
-  4. `git diff <base> --name-only --diff-filter=ACMR` — **без** `..`/`...`, **без** `HEAD`. Така форма порівнює base-комміт із поточним **робочим деревом**, тобто ловить одночасно: закомічене від base, staged та незакомічені модифікації.
-  5. `git ls-files --others --exclude-standard` — untracked файли (як у `collectChangedFiles`).
-  6. Дедуплікація через `Set`.
-- **Повертає:** `string[]` — унікальні relative-posix шляхи без видалених файлів.
-- **Контракт fail-closed:** на відміну від `collectChangedFiles`, ця функція **навмисно** не маскує помилку недосяжного base. Інакше `git diff` повернув би exit 128, `gitLines` дав би `[]`, і gate мовчки пройшов би без перевірки — це порушує безпеку coverage-перевірки.
-- **Side effects:**
-  - спавнить два-три git-процеси (один verify + два data-збори, або один fallback);
-  - може кинути `Error` (єдина точка throw у модулі).
-
-## Залежності
-
-### Зовнішні (built-in Node.js)
-
-- `node:child_process` — імпорт `spawnSync` для синхронного виклику git-команд із захопленням stdout.
-
-### Системні (runtime)
-
-- `git` — має бути доступний у `PATH` процесу. За відсутності `gitLines` поверне `[]` (через `r.error`/ненульовий статус).
-
-### Внутрішні модулі
-
-Файл не імпортує жодного локального модуля проєкту (zero-dependency бібліотечний листок).
-
-## Потік виконання / Використання
-
-### Quick-lint (lint-оркестратор)
-
-```js
-import { collectChangedFiles } from './changed-files.mjs'
-
-const files = collectChangedFiles()
-// → лінт тільки цих файлів, замість обходу всього монорепо
-```
-
-Quick-режим прагне мінімізувати IO: лінтить лише те, що користувач щойно змінив у дереві (modified + staged + untracked), ігноруючи решту репо.
-
-### Coverage / flow-турнікет
-
-```js
-import { collectChangedFilesSince } from './changed-files.mjs'
-
-const base = metadata.base_commit // SHA, зафіксований при старті flow-кроку
-const scope = collectChangedFilesSince(base, repoRoot)
-// → файли, які змінилися з моменту base, незалежно від того,
-//   чи їх вже закомічено в проміжних кроках executor-а
-```
-
-Чому саме `git diff <base>` без `..`/`...`:
-
-- `git diff A..B` — порівнює дерева A та B, **ігнорує** робоче дерево;
-- `git diff A...B` — порівнює B з merge-base(A,B), теж ігнорує робоче дерево;
-- `git diff <base>` (один аргумент) — порівнює `<base>` із **робочим деревом** (включно з unstaged змінами).
-
-Це критично для flow-турнікета, де executor може як комітити проміжні зміни, так і залишати їх unstaged — gate повинен побачити всі зміни від `base` однаково.
-
-### Поведінка при недосяжному base
+Файл збирає змінені та незакомічені файли з робочого дерева. Визначає базовий комміт для перевірок у межах зміненого діапазону. Збирає змінені та незакомічені файли відносно базового комміту.
 
-Якщо у репозиторії стався rebase, force-push або shallow clone обрізав історію — `<base>` може стати недосяжним. У такому разі:
+## Поведінка
 
-- `collectChangedFiles` (без base) — поведінка незмінна, працює від `HEAD`;
-- `collectChangedFilesSince(base, cwd)` — **кидає Error** до того, як викликати `git diff`, щоб coverage-gate явно впав, а не пройшов на порожньому scope.
+collectChangedFiles Збирає змінені та незакомічені файли з робочого дерева.
+resolveChangedBase Визначає базовий комміт для scoped-перевірок.
+collectChangedFilesSince Збирає змінені та незакомічені файли відносно базового комміту.
 
-### Формат шляхів
+## Публічний API
 
-Усі повернені шляхи — POSIX-style relative до `cwd` (як їх віддає git за замовчуванням). На Windows git також віддає forward slashes, тож додаткової нормалізації немає.
+- collectChangedFiles: Збирає список змінених та невідстежених файлів з робочого дерева відносно робочого дерева.
+- resolveChangedBase: Визначає базовий комміт для обмежених перевірок без використання зовнішнього стану.
+  - Пріоритет: локальна `main`, потім `origin/main`.
+  - Якщо обидві відсутні, повертає null, і викликаючий порівнює лише робоче дерево з HEAD.
+- collectChangedFilesSince: Збирає список змінених та невідстежених файлів відносно базового комміту.
+- git diff <base>: Порівнює комміт `base` з поточним робочим деревом (включаючи закомічені та незакомічені модифікації).
+  - Якщо `base` відсутній, використовується `collectChangedFiles`.
 
-### Точки помилок (summary)
+## Гарантії поведінки
 
-| Сценарій                                      | Поведінка                                                                                                                          |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Поза git-репо                                 | `collectChangedFiles` → `[]`; `collectChangedFilesSince(null)` → `[]`; `collectChangedFilesSince('SHA')` → `Error` (verify впаде). |
-| `git` відсутній у PATH                        | Усі виклики `gitLines` → `[]`; `collectChangedFilesSince` із `base` → `Error` (verify впаде).                                      |
-| `base` досяжний                               | `collectChangedFilesSince` повертає список (можливо порожній).                                                                     |
-| `base` недосяжний (rebase/force-push/shallow) | `collectChangedFilesSince` кидає `Error`.                                                                                          |
-| `base` falsy (`null`/`undefined`/`''`/`0`)    | `collectChangedFilesSince` → результат `collectChangedFiles(cwd)`.                                                                 |
+- Read-only: файл не виконує операцій запису у файлову систему.
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.