@nitra/cursor 12.6.0 → 12.7.0

package/rules/text/{lint/lint.mjs → main.mjs}

@@ -13,21 +13,33 @@
  * з неінформативним повідомленням. ensureTool збирає всі відсутні бінарники до першого кроку.
  *
  * Перший ненульовий код з ланцюжка повертається як код виходу; наступні кроки не запускаються.
- * Експортовано як `runLintTextCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-text`.
+ * Експортовано як `runLintTextCli` — викликається через `n-cursor lint text` (оркестраторний адаптер `lint()` делегує сюди); окремої bin-підкоманди `lint-text` немає.
  *
  * Канон патерну `lint-*` (серіалізація через `runStandardLint`, без прямого `withLock`) —
  * `.cursor/rules/scripts.mdc`, секція «Серіалізація важких CLI-команд».
  */
 import { platform } from 'node:process'
 
-import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
-import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
-import { runCspellText } from './cspell-fix.mjs'
-import { runDotenvLinter } from './run-dotenv-linter.mjs'
-import { runShellcheckText } from './run-shellcheck.mjs'
-import { runV8rWithGlobs } from './run-v8r.mjs'
+import { runLintStep } from '../../scripts/lib/run-lint-step.mjs'
+import { resolveCmd } from '../../scripts/utils/resolve-cmd.mjs'
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+import { ensureTool } from '../../scripts/lib/ensure-tool.mjs'
+import { runCspellText } from './js/cspell-fix.mjs'
+import { runDotenvLinter } from './js/run-dotenv-linter.mjs'
+import { runShellcheckText } from './js/run-shellcheck.mjs'
+import { runV8rWithGlobs } from './js/run-v8r.mjs'
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня (applies → JS-concerns
+ * → policy → mdc-refs); `lint()` нижче — lint-поверхня (markdownlint/cspell/shellcheck/…), імпл інлайн тут.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
 
 /**
  * Опис залежності preflight-ом.
@@ -136,3 +148,20 @@ function runLintTextSteps(readOnly = false, llmFix = false) {
  */
 export const runLintTextCli = (opts = {}) =>
   runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true, opts.llmFix === true))
+
+/**
+ * Оркестраторний адаптер `n-cursor lint text`: делегує у `runLintTextCli`.
+ * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
+ * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу;
+ *   llmFix → opt-in omlx-класифікація cspell
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, _cwd, opts = {}) {
+  return runLintTextCli({ readOnly: opts.readOnly === true, llmFix: opts.llmFix === true })
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/text/main.mjs — повний еквівалент `npx @nitra/cursor check text`.
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/text/text.mdc

@@ -117,19 +117,16 @@ version: '1.30'
 
 Завжди пиши **JSDoc** до функцій та методів.
 
-**`package.json`:** скрипт **`lint-text`** і devDependencies **`@nitra/cspell-dict`** (**`^2.0.0`** або новіший у лінії 2.x) — з **2.0.0** у пакет транзитивно входять типові **`@cspell/dict-*`**, тому **не** додавай їх окремо в корінь. **`markdownlint-cli2`** викликай у `lint-text` лише через **`bunx markdownlint-cli2`**, не додавай пакет до devDependencies. **`v8r`** лише через **`bunx v8r`** (зазвичай **`bunx v8r`**), не в devDependencies. Окремий пакет **`markdownlint`** не потрібний.
+**`package.json`:** у `devDependencies` має бути **`@nitra/cspell-dict`** (**`^2.0.0`** або новіший у лінії 2.x) — з **2.0.0** у пакет транзитивно входять типові **`@cspell/dict-*`**, тому **не** додавай їх окремо в корінь. Окремий `package.json`-скрипт `lint-text` не потрібен: запуск іде через **`n-cursor lint text`**. **`markdownlint-cli2`** запускається rule-адаптером через **`bunx markdownlint-cli2`**, не додавай пакет до devDependencies. **`v8r`** лише через **`bunx v8r`**, не в devDependencies. Окремий пакет **`markdownlint`** не потрібний.
 
-**shellcheck:** інструмент лише в **`PATH`** (як у **ga.mdc** для `lint-ga`), **не** додавай до `dependencies` / `devDependencies`. Якщо `shellcheck` відсутній — встанови локально (**macOS:** `brew install shellcheck`; **Debian/Ubuntu:** `sudo apt-get install -y shellcheck`; **Arch:** `sudo pacman -S shellcheck`). Канонічний **`lint-text`** делегує до CLI **`n-cursor lint-text`** (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`): після **`cspell .`** виконується **`runShellcheckText()`** з пакета — циклічно **`shellcheck -f diff`** і **`patch -p1`** для авто-виправлень, потім повний прогін **`shellcheck`** по всіх tracked `*.sh` (у git) або по `**/*.sh` без `node_modules`. Потрібен також **`patch`** у `PATH` (на macOS зазвичай уже є).
+**shellcheck:** інструмент лише в **`PATH`** (як у **ga.mdc** для `lint-ga`), **не** додавай до `dependencies` / `devDependencies`. Якщо `shellcheck` відсутній — встанови локально (**macOS:** `brew install shellcheck`; **Debian/Ubuntu:** `sudo apt-get install -y shellcheck`; **Arch:** `sudo pacman -S shellcheck`). Канонічний запуск — **`n-cursor lint text`** (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`): після **`cspell .`** виконується **`runShellcheckText()`** з пакета — циклічно **`shellcheck -f diff`** і **`patch -p1`** для авто-виправлень, потім повний прогін **`shellcheck`** по всіх tracked `*.sh` (у git) або по `**/*.sh` без `node_modules`. Потрібен також **`patch`** у `PATH` (на macOS зазвичай уже є).
 
 **dotenv-linter:** після shellcheck CLI запускає **`runDotenvLinter()`** з пакета — рекурсивно по `.env*`-файлах проєкту через **`dotenv-linter fix -r --no-backup --quiet . --exclude node_modules --exclude .envrc`**, далі такий самий **`check`** для фінальної перевірки. Інструмент має бути в **`PATH`** і **не** додається в `dependencies` / `devDependencies`. Якщо `dotenv-linter` відсутній — встанови локально (**macOS:** `brew install dotenv-linter`; **Linux:** `curl -sSfL https://git.io/JLbXn | sh -s -- -b /usr/local/bin`; через **cargo:** `cargo install dotenv-linter`).
 
-У v8r **немає** прапорця тихого режиму; CLI-обгортка **`n-cursor lint-text`** на четвертому кроці викликає **`runV8rWithGlobs()`** з пакета (реалізація — `npm/rules/text/js/run-v8r.mjs`): під капотом послідовні **`bunx v8r`** для кожного типу (**json**, **json5**, **yml**, **yaml**, **toml**), бо один процес v8r з кількома глобами падає з **98**, якщо хоч один glob порожній, і тоді інші розширення не перевіряються. Вивід при кодах **0** і **98** не показується. Каталог схем **`schemas/v8r-catalog.json`** пакета `@nitra/cursor` обгортка підставляє в v8r сама.
+У v8r **немає** прапорця тихого режиму; rule-адаптер **`n-cursor lint text`** на четвертому кроці викликає **`runV8rWithGlobs()`** з пакета (реалізація — `npm/rules/text/js/run-v8r.mjs`): під капотом послідовні **`bunx v8r`** для кожного типу (**json**, **json5**, **yml**, **yaml**, **toml**), бо один процес v8r з кількома глобами падає з **98**, якщо хоч один glob порожній, і тоді інші розширення не перевіряються. Вивід при кодах **0** і **98** не показується. Каталог схем **`schemas/v8r-catalog.json`** пакета `@nitra/cursor` обгортка підставляє в v8r сама.
 
 ```json title="package.json"
 {
-  "scripts": {
-    "lint-text": "n-cursor lint-text"
-  },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
   }
@@ -174,7 +171,7 @@ version: '1.30'
 
 - Канон: [lint-text.yml.snippet.yml](./policy/lint_text/template/lint-text.yml.snippet.yml)
 
-Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Після composite — кроки **`Install shellcheck`** (apt) і **`Install dotenv-linter`** (curl), бо `n-cursor lint-text` вимагає обидва бінарники в PATH; на ubuntu-latest shellcheck часто вже є, dotenv-linter — ні. Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
+Перед **`./.github/actions/setup-bun-deps`** — **`actions/checkout@v6`** (див. **ga.mdc**). Після composite — кроки **`Install shellcheck`** (apt) і **`Install dotenv-linter`** (curl), бо `n-cursor lint text` вимагає обидва бінарники в PATH; на ubuntu-latest shellcheck часто вже є, dotenv-linter — ні. Composite: Node 24, Bun, кеш, `bun install --frozen-lockfile`.
 
 Не дублюй окремий workflow з тими самими кроками cspell/markdownlint.
 
@@ -198,9 +195,6 @@ version: '1.30'
 
 ```json title="package.json"
 {
-  "scripts": {
-    "lint-text": "n-cursor lint-text"
-  },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
   }
@@ -215,9 +209,6 @@ version: '1.30'
 
 ```json title="package.json"
 {
-  "scripts": {
-    "lint-text": "n-cursor lint-text"
-  },
   "devDependencies": {
     "@nitra/cspell-dict": "^2.1.0"
   }
@@ -262,4 +253,4 @@ kebab-case
 
 ## Перевірка
 
-`npx @nitra/cursor fix text` (охоплює oxfmt, cspell, shellcheck у `lint-text`, markdownlint, v8r, CI для `lint-text`). Зокрема падає, якщо у корені є `.prettierignore`, `.prettierrc*`, `prettier.config.*` або у `package.json#scripts` зустрічається команда з `prettier` — Prettier повністю заборонено, форматування лише через **oxfmt**.
+`npx @nitra/cursor fix text` (охоплює oxfmt, cspell, shellcheck, markdownlint, v8r і CI для `n-cursor lint text`). Зокрема падає, якщо у корені є `.prettierignore`, `.prettierrc*`, `prettier.config.*` або у `package.json#scripts` зустрічається команда з `prettier` — Prettier повністю заборонено, форматування лише через **oxfmt**.

package/rules/tool-surface/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/tool-surface/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/tool-surface/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/tool-surface/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує валідацію контенту, застосовуючи правила, визначені в конфігурації, що зчитується з meta.json. Він обробляє запити, пов'язані з JavaScript, та взаємодіє з MDC. При запуску як CLI, він ініціалізує та виконує повний цикл перевірки, надаючи фінальний звіт.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки поверхні.
+2. Виконання перевірки поверхні включає застосування політик, обробку JS-запитань та посилання на MDC.
+3. Якщо код виконується як окремий інструмент (CLI), виконується оркестрація правила.
+4. Оркестрація правила зчитує конфігурацію з `meta.json` та виконує повний цикл перевірки, включаючи підсумок.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, аналізує JS-залежності та політику, а також перевіряє посилання на MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/tool-surface/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * 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>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/vue/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/vue/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/vue/docs/main.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/vue/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку, застосовуючи політику та обробляючи логіку JavaScript. Він забезпечує повний запуск правила, завантажуючи конфігурації, такі як meta.json, застосовуючи білі списки та підбиваючи підсумки. При запуску як окрема утиліта командного рядка, виконується повний цикл перевірки через публічну функцію run. Модуль є Read-only і кешує дані у межах прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки включає застосування політики, обробку логіки, пов'язаної з JavaScript, та посилання на MDC-референси.
+3. Якщо скрипт виконується як окрема утиліта командного рядка, виконується повний запуск правила.
+4. Повний запуск правила включає завантаження конфігурацій (наприклад, `meta.json`), застосування білих списків та підбиття підсумків.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує перевірки, обробляє JS-залежності та політику, а також посилається на метадані.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/vue/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * 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>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/worktree/docs/index.md

@@ -9,3 +9,4 @@ resource: npm/rules/worktree/
 | Файл | Тип |
 |---|---|
 | [fix.mjs](fix.md) | JS Module |
+| [main.mjs](main.md) | JS Module |

package/rules/worktree/docs/main.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/worktree/main.mjs
+docgen:
+  crc: 762b6875
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль виконує перевірку, застосовуючи політики, визначені в meta.json. Він обробляє JS-запити та звертається до MDC-ресурсів. Модуль є Read-only, тобто не здійснює записів у файлову систему чи бази даних. При запуску як окрема утиліта командного рядка, він виконує правила, використовуючи публічну функцію run. Дані кешуються у межах одного прогону.
+
+## Поведінка
+
+1. Викликається функція `run` для виконання перевірки.
+2. Виконання перевірки включає застосування політик, обробку JS-запитань та посилання на MDC-ресурси.
+3. Якщо скрипт виконується як окрема утиліта командного рядка, запускається повний процес виконання правила.
+
+## Публічний API
+
+run — виконує основну логіку правила: застосовує JS-залежності, перевіряє політику та посилання MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/worktree/main.mjs

@@ -0,0 +1,20 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Єдиний entrypoint правила (ADR 2026-06-21). `run()` — check-поверхня: applies →
+ * JS-concerns → policy → mdc-refs (через runStandardRule). Lint-поверхні правило не має
+ * (`meta.json` без `lint`), тож експорту `lint` тут немає.
+ * 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>/main.mjs — повний еквівалент `npx @nitra/cursor check <id>`
+  // (config-loading + whitelist + summary): library-роль (run) + standalone-роль (CLI-блок).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/scripts/docs/index.md

@@ -15,6 +15,7 @@ resource: npm/scripts/
 | [coverage-fix-extract.mjs](coverage-fix-extract.md) | JS Module |
 | [coverage-fix.mjs](coverage-fix.md) | JS Module |
 | [ensure-nitra-cursor-dev-dependencies.mjs](ensure-nitra-cursor-dev-dependencies.md) | JS Module |
+| [post-tool-use-check.mjs](post-tool-use-check.md) | JS Module |
 | [post-tool-use-fix.mjs](post-tool-use-fix.md) | JS Module |
 | [rename-yaml-extensions.mjs](rename-yaml-extensions.md) | JS Module |
 | [skills-cli.mjs](skills-cli.md) | JS Module |

package/scripts/docs/post-tool-use-check.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: post-tool-use-check.mjs
+resource: npm/scripts/post-tool-use-check.mjs
+docgen:
+  crc: 7d2faa18
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Цей модуль є PostToolUse hook, який виконує read-only детект конформності всіх активованих правил після кожного редагування файлу (`Edit` / `Write` / `MultiEdit`). Він отримує шлях до файлу з вхідного JSON. Якщо файл відсутній, модуль завершує роботу з кодом 0. Інакше, він запускає детект конформності по всіх правилах, не виконуючи жодних мутацій чи викликів LLM. Код виходу 1 інформує про наявність порушень конформності, хоча PostToolUse не блокує поточний обмін.
+
+## Поведінка
+
+extractFilePath зчитує JSON із вхідного потоку та витягує відносний шлях до файлу, повертаючи його або `null` у разі невалідного JSON чи відсутності поля.
+runPostToolUseCheckCli зчитує вхідні дані, визначає шлях до файлу та виконує перевірку конформності всіх активованих правил, повертаючи код виходу 0, якщо порушень немає, або 1, якщо є порушення конформності.
+
+## Публічний API
+
+extractFilePath — витягує шлях до файлу з вхідних даних JSON, повертаючи `null`, якщо JSON недійсний або поле відсутнє.
+runPostToolUseCheckCli — ініціює перевірку після використання інструменту при запуску з `bin/n-cursor.js` з аргументом `post-tool-use-check`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

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

@@ -3,108 +3,80 @@ type: JS Module
 title: sync-claude-config.mjs
 resource: npm/scripts/sync-claude-config.mjs
 docgen:
-  crc: ad7b8440
-  score: 95
+  crc: 88f4080d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 85
 ---
 
-Файл синхронізує конфігурацію Claude Code (`.claude/settings.json`), slash-команди з темплейту та Cursor hooks (`.cursor/hooks.json`) у поточний проєкт з використанням темплейтів пакету `npm/.claude-template/`. Він виконує злиття користувацьких полів, дозволів та хуків з різних джерел. Синхронізуються та видаляються залежні скрипти та фрагменти конфігурації.
+## Огляд
 
-## Поведінка
-
-MANAGED_HOOK_COMMAND_MARKER Маркер PostToolUse fix-hook
-
-DOC_FILES_HOOK_COMMAND_MARKER Маркер doc-files staleness-hook
-
-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'ів
+Синхронізує конфігурацію Claude Code (`.claude/settings.json`, slash-команди з `commands/` темплейту, ADR Stop-hook) та Cursor hooks (`.cursor/hooks.json`) у поточний проєкт із темплейтів пакету `npm/.claude-template/`. Здійснює злиття конфігурацій: користувацькі поля зберігаються у `.claude/settings.json`, а дозволи (`permissions.allow`) зливаються через union. Керовані хуки, ідентифіковані командою-маркером `MANAGED_HOOK_COMMAND_MARKERS`, перезаписуються. Копіює ADR Stop-hook (`.claude/hooks/capture-decisions.sh`) та ADR normalize Stop-hook (`.claude/hooks/normalize-decisions.sh`) залежно від налаштувань у `.n-cursor.json`. Також зливає фрагмент `.gitignore` з канонічного шаблону, додаючи необхідні записи для ADR.
 
-mergeAllowList Зливає список allow-permissions без дублікатів
-
-mergeHooks Зливає hooks-секцію, видаляючи managed-групи з існуючої конфігурації
-
-mergeSettings Зливає конфігурацію Claude, перевіряючи та зливаючи permissions та hooks
-
-mergeCursorHooksConfig Зливає конфігурацію Cursor, керуючи додаванням/видаленням ADR stop entries
-
-syncCursorHooksConfig Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks
-
-syncClaudeSettings Синхронізує `.claude/settings.json` за темплейтом
-
-syncAdrHookScript Копіює канонічний bash-скрипт ADR capture Stop-hook з темплейту
-
-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-конфігу з темплейту
+MANAGED_HOOK_COMMAND_MARKER — Визначає маркер для хука `post-tool-use-check`.
+DOC_FILES_HOOK_COMMAND_MARKER — Визначає маркер для хука `lint-doc-files`.
+LEGACY_DOC_FILES_HOOK_COMMAND_MARKER — Визначає маркер для застарілого хука `doc-files check`.
+LEGACY_STOP_HOOK_COMMAND_MARKER — Визначає маркер для застарілого Stop-hook'а.
+ADR_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR capture Stop-hook.
+ADR_NORMALIZE_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR normalize Stop-hook.
+CURSOR_ADR_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR capture Stop-hook у `.cursor/hooks.json`.
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-скрипта ADR normalize Stop-hook у `.cursor/hooks.json`.
+MANAGED_HOOK_COMMAND_MARKERS — Містить список усіх маркерів, що ідентифікують керовані хуки пакета.
+PI_DIR — Визначає кореневу директорію для артефактів pi.dev у проєкті-споживачі.
+PI_EXTENSIONS_DIR — Визначає директорію для TS-extensions pi.dev у проєкті-споживачі.
+PI_TEMPLATE_DIR_NAME — Визначає назву директорії з темплейтом pi-template у пакеті.
+PI_EXTENSION_NAME — Визначає ім'я bundled pi-extension для ADR capture/normalize.
+ADR_GITIGNORE_SNIPPET_REL — Визначає відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета.
+mergeAllowList — Об'єднує списки дозволених дозволів, зберігаючи користувацькі записи першими.
+mergeHooks — Зливає секцію `hooks` з `.claude/settings.json`, видаляючи керовані групи з існуючої конфігурації.
+mergeSettings — Зливає конфігурацію `.claude/settings.json` з темплейту, зберігаючи користувацькі поля та оновлюючи керовані хуки.
+mergeCursorHooksConfig — Зливає конфігурацію `.cursor/hooks.json`, зберігаючи користувацькі записи та додаючи/видаляючи керовані ADR stop entries.
+syncCursorHooksConfig — Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks, додаючи ADR entries за умовою.
+syncClaudeSettings — Синхронізує `.claude/settings.json` за темплейтом, зберігаючи користувацькі налаштування.
+syncAdrHookScript — Копіює канонічний bash-скрипт ADR capture Stop-hook з темплейту пакета у `.claude/hooks/`.
+syncAdrNormalizeHookScript — Копіює канонічний bash-скрипт ADR normalize Stop-hook з темплейту пакета у `.claude/hooks/`.
+syncAdrHookLibScripts — Копіює всі bash-скрипти з `lib/` темплейту у `.claude/hooks/lib/` проєкту.
+removeOrphanAdrHookLib — Видаляє директорію `.claude/hooks/lib/` з проєкту, якщо ADR-хуки вимкнені.
+syncPiExtensions — Копіює bundled pi.dev TS-extension `n-cursor-adr` у `.pi/extensions/n-cursor-adr/` проєкту.
+removeOrphanPiExtension — Видаляє директорію `.pi/extensions/n-cursor-adr/` з проєкту, якщо ADR-хуки вимкнені.
+syncGitignoreAdrFragment — Дописує відсутні рядки з канонічного ADR-фрагмента до кореневого `.gitignore` проєкту.
+syncClaudeCommands — Копіює всі slash-команди з `.claude-template/commands/` у `.claude/commands/` проєкту.
+syncClaudeConfig — Виконує повну синхронізацію Claude Code-конфігу, включаючи ADR-хуки, `.gitignore` та pi-extension, залежно від правил.
 
 ## Публічний 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` після інших синків.
+MANAGED_HOOK_COMMAND_MARKER — Позначає хук для перевірки після використання інструменту.
+DOC_FILES_HOOK_COMMAND_MARKER — Позначає хук для перевірки актуальності файлів документації.
+LEGACY_DOC_FILES_HOOK_COMMAND_MARKER — Позначає старий маркер для очищення хуків документації.
+LEGACY_STOP_HOOK_COMMAND_MARKER — Позначає старий маркер для очищення хука зупинки.
+ADR_HOOK_COMMAND_MARKER — Позначає шлях до скрипта для фіксації рішень ADR.
+ADR_NORMALIZE_HOOK_COMMAND_MARKER — Позначає шлях до скрипта для нормалізації рішень ADR.
+CURSOR_ADR_HOOK_COMMAND_MARKER — Позначає шлях до скрипта фіксації ADR у конфігурації Cursor.
+CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER — Позначає шлях до скрипта нормалізації ADR у конфігурації Cursor.
+MANAGED_HOOK_COMMAND_MARKERS — Групує всі маркери хуків, щоб відрізнити автоматичні записи від користувацьких.
+PI_DIR — Місце зберігання артефактів pi.dev у проєкті.
+PI_EXTENSIONS_DIR — Директорія для TS-розширень pi.dev у проєкті.
+PI_TEMPLATE_DIR_NAME — Назва папки з шаблоном pi у пакеті.
+PI_EXTENSION_NAME — Ім'я пакета pi-розширення для фіксації/нормалізації ADR.
+ADR_GITIGNORE_SNIPPET_REL — Відносний шлях до шаблону `.gitignore` для ADR.
+mergeAllowList — Об'єднує дозволені права доступу, зберігаючи порядок існуючих записів.
+mergeHooks — Об'єднує секцію хуків: видаляє автоматичні записи з існуючої конфігурації та додає записи з шаблону.
+mergeSettings — Створює об'єднаний файл налаштувань.
+mergeCursorHooksConfig — Об'єднує конфігурацію хуків Cursor, зберігаючи користувацькі записи та оновлюючи ADR-записи.
+syncCursorHooksConfig — Синхронізує конфігурацію зупинки для агента Cursor.
+syncClaudeSettings — Копіює налаштування Claude Code з шаблону, зберігаючи користувацькі дані.
+syncAdrHookScript — Копіює канонічний скрипт фіксації рішень ADR.
+syncAdrNormalizeHookScript — Копіює канонічний скрипт нормалізації рішень ADR.
+syncAdrHookLibScripts — Копіює всі допоміжні скрипти з шаблону в проєкт.
+removeOrphanAdrHookLib — Видаляє директорію з допоміжними скриптами ADR, якщо правило ADR вимкнено.
+syncPiExtensions — Копіює TS-розширення pi.dev у проєкт.
+removeOrphanPiExtension — Видаляє директорію з розширення pi, якщо правило ADR вимкнено.
+syncGitignoreAdrFragment — Додає необхідні рядки з канонічного фрагмента `.gitignore` до кореня проєкту.
+syncClaudeCommands — Копіює всі slash-команди з шаблону в директорію команд Claude.
+syncClaudeConfig — Виконує повну синхронізацію конфігурації Claude Code з шаблону.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Свідомо пропускає шляхи: `.git`.
-- Не звертається до мережі.

package/scripts/lib/adr/docs/normalize-cli.md

@@ -6,11 +6,8 @@ docgen:
   crc: 63a18347
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-## Огляд
-
 Цей файл є CLI-обгорткою для локального нормалізатора ADR. Він зчитує шляхи до чернеток (`--batch <file>`) та список чистих ADR (`--clean <file>`), використовуючи директорію ADR (`--adr-dir <dir>`) для резолву шляхів. Обгортка запускає `normalizePipeline`, яка генерує JSON-контракт у форматі `{ "operations": [...] }` та виводить його у stdout для подальшого парсингу bash-скриптом. Прогрес та помилки записуються у stderr. Поведінка нормалізатора може бути змінена через змінні середовища: `ADR_NORMALIZE_ALLOW_CLOUD` контролює можливість хмарної ескалації, а `ADR_NORMALIZE_VOTES` визначає кількість голосів self-consistency для чистих ADR.
 
 ## Поведінка

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -7,11 +7,8 @@ docgen:
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-## Огляд
-
 Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток архітектурних рішень (ADR). Він працює за принципом інверсії керування: JavaScript оркеструє процес, а LLM відповідає лише на вузькі, верифіковані запитання, будучи заточеним під малу локальну модель (omlx/gemma-4b). LLM використовується лише для бінарного судження схожості між записами (наприклад, через `edge-judge`) та витягування змісту секцій у JSON (через `gen-MADR`). Конвеєр збирає, валідує та складає повний MADR-каркас, використовуючи кластеризацію (`cluster` та `union-find`) та проходить через `validation gate`, повертаючи результат у вигляді операцій для застосування.
 
 ## Поведінка