@nitra/cursor 12.6.1 → 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/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`, повертаючи результат у вигляді операцій для застосування.
 
 ## Поведінка