@7n/rules 1.3.2 → 1.4.1

package/.pi-template/extensions/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/.pi-template/extensions
+resource: npm/.pi-template/extensions/
+---
+
+| Файл             | Тип       |
+| ---------------- | --------- |
+| [rtk.ts](rtk.md) | TS Module |

package/.pi-template/extensions/docs/rtk.md

@@ -0,0 +1,33 @@
+---
+type: TS Module
+title: rtk.ts
+resource: npm/.pi-template/extensions/rtk.ts
+docgen:
+  crc: f00b429f
+---
+
+## Огляд
+
+Pi.dev-extension для rtk (Rust Token Killer): прозоро переписує bash-команди агента на
+rtk-еквіваленти, щоб стискати вивід CLI-команд і економити токени. Vendored із rtk
+(`rtk init --agent pi`), адаптований під конвенції репо; доставляється sync-ом пакета
+`@7n/rules` у `.pi/extensions/rtk.ts` проєктів-споживачів, коли увімкнене правило
+`local-ai`. Шлях збігається зі шляхом установки самого rtk, тож ручний
+`rtk init --agent pi` поверх — ідемпотентний.
+
+## Поведінка
+
+- Тонкий делегат: рішення про переписування ухвалює `rtk rewrite <cmd>` (exit 0 або 3 +
+  stdout → команда мутується через `event.input.command`; exit 1 — passthrough).
+- При завантаженні пробує `rtk --version`: без бінарника в PATH або з rtk < 0.23.0
+  extension сам вимикається з `console.warn` (fail-open) — установка конфігу безпечна
+  до `brew install rtk-ai/tap/rtk`.
+- Пропускає без змін: не-bash tool_call, порожні команди, команди, що вже починаються
+  з `rtk `, і будь-що при `RTK_DISABLED=1` в env.
+- Виклики rtk обмежені таймаутом 2 с і сигналом скасування контексту; будь-яка
+  неочікувана помилка в обробнику лише логується — команда виконується без переписування.
+
+## Гарантії поведінки
+
+- Fail-open: жоден збій rtk/extension не блокує виконання команди агента.
+- Мутує лише `event.input.command` у pi tool_call — жодних записів у ФС чи мережевих викликів.

package/.pi-template/extensions/rtk.ts

@@ -0,0 +1,102 @@
+// RTK Pi extension — переписує bash-команди на rtk-еквіваленти для економії токенів.
+// Vendored з rtk (`rtk init --agent pi`, rtk 0.43.0), адаптований під конвенції репо:
+// без імпортів з '@earendil-works/pi-coding-agent' (пакет резолвиться лише в runtime pi,
+// а knip/TS-server проєктів-споживачів його не бачать) — типи описані локально, як у
+// n-rules-adr. Шлях установки `.pi/extensions/rtk.ts` збігається зі шляхом самого rtk —
+// повторний `rtk init --agent pi` ідемпотентний. Потребує rtk >= 0.23.0 у PATH; без
+// нього extension сам вимикається (fail-open).
+//
+// Тонкий делегат: уся rewrite-логіка живе в `rtk rewrite` (єдине джерело правди).
+//
+// Контракт exit-кодів `rtk rewrite`:
+//   0 + stdout  rewrite знайдено → мутуємо команду
+//   1           rtk-еквівалента немає → passthrough
+//   3 + stdout  rewrite (advisory) → мутуємо команду
+
+import { env } from 'node:process'
+
+interface PiToolCallEvent {
+  toolName?: string
+  input: { command?: unknown }
+}
+
+interface PiContext {
+  signal?: AbortSignal
+}
+
+interface PiExecResult {
+  code: number
+  stdout: string
+  killed?: boolean
+}
+
+interface PiApi {
+  exec: (cmd: string, args: string[], opts?: { timeout?: number; signal?: AbortSignal }) => Promise<PiExecResult>
+  on: (event: string, handler: (event: PiToolCallEvent, ctx: PiContext) => Promise<void> | void) => void
+}
+
+const REWRITE_TIMEOUT_MS = 2_000
+const MIN_SUPPORTED_RTK_MINOR = 23
+
+const SEMVER_RE = /(\d+)\.(\d+)\.(\d+)/
+const RTK_VERSION_PREFIX_RE = /^rtk\s+/
+
+// Парсить "X.Y.Z" semver → [major, minor, patch] або null.
+function parseSemver(raw: string): [number, number, number] | null {
+  const m = raw.trim().match(SEMVER_RE)
+  if (!m) return null
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)]
+}
+
+// Викликає `rtk rewrite`; повертає переписану команду або null (passthrough).
+async function rewriteCommand(pi: PiApi, cmd: string, signal?: AbortSignal): Promise<string | null> {
+  const result = await pi.exec('rtk', ['rewrite', cmd], {
+    timeout: REWRITE_TIMEOUT_MS,
+    signal
+  })
+  if (result.killed) return null
+  if (result.code !== 0 && result.code !== 3) return null
+  return result.stdout.trim() || null
+}
+
+export default async function (pi: PiApi) {
+  // Проба rtk при завантаженні; без бінарника (або із застарим) extension вимикається.
+  const ver = await pi.exec('rtk', ['--version'], { timeout: REWRITE_TIMEOUT_MS })
+  if (ver.code !== 0) {
+    console.warn('[rtk] rtk binary not found in PATH — extension disabled')
+    return
+  }
+
+  // `rtk rewrite` з'явився у 0.23.0 — старіші версії не підтримуються.
+  const parsed = parseSemver(ver.stdout.replace(RTK_VERSION_PREFIX_RE, ''))
+  if (parsed) {
+    const [major, minor] = parsed
+    if (major === 0 && minor < MIN_SUPPORTED_RTK_MINOR) {
+      console.warn(`[rtk] rtk ${ver.stdout.trim()} is too old (need >= 0.23.0) — extension disabled`)
+      return
+    }
+  }
+
+  pi.on('tool_call', async (event, ctx) => {
+    try {
+      // В upstream це isToolCallEventType('bash', event) — просте порівняння toolName.
+      if (event?.toolName !== 'bash') return
+
+      const cmd = event.input.command
+      if (typeof cmd !== 'string' || cmd.trim() === '') return
+
+      if (cmd.startsWith('rtk ')) return
+      if (env.RTK_DISABLED === '1') return
+
+      // Делегуємо rewrite-рішення rtk.
+      const rewritten = await rewriteCommand(pi, cmd, ctx.signal)
+      if (rewritten && rewritten !== cmd) {
+        event.input.command = rewritten
+      }
+    } catch (error) {
+      // Fail open: ніколи не блокуємо виконання через неочікувану помилку.
+      console.warn('[rtk] unexpected error in tool_call handler; passing through command', error)
+      return
+    }
+  })
+}

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.4.1] - 2026-07-15
+
+### Fixed
+
+- Виправлено застарілі шляхи npm/rules/js/js/data/tooling у повідомленнях перевірок tooling/check (пост-реструктуризація da05f89d)
+
+## [1.4.0] - 2026-07-15
+
+### Added
+
+- Нове правило `local-ai` (auto: завжди): інтеграція rtk (Rust Token Killer) для стискання виводу CLI-команд агентів. Sync вставляє fail-open PreToolUse hook у `.claude/settings.json` (`rtk hook claude`), preToolUse у `.cursor/hooks.json` (`rtk hook cursor`) та vendored pi-extension `.pi/extensions/rtk.ts`; від користувача потрібен лише `brew install rtk-ai/tap/rtk`. Вимкнення — `disable-rules: ["local-ai"]`.
+
 ## [1.3.2] - 2026-07-15
 
 ### Fixed

package/bin/n-rules.js

@@ -1458,6 +1458,7 @@ async function runSync() {
       }
       if (result.gitignoreAdr) parts.push('.gitignore (adr fragment)')
       if (result.piExtension) parts.push('.pi/extensions/n-rules-adr/')
+      if (result.rtkPiExtension) parts.push('.pi/extensions/rtk.ts')
       if (parts.length > 0) {
         console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
       }

package/package.json

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

package/rules/js/check/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/js/check/main.mjs
 docgen:
-  crc: 97d3723c
+  crc: 8858d876
   model: manual
 ---
 

package/rules/js/check/main.mjs

@@ -285,7 +285,7 @@ async function checkKnipConfig(passFn, failFn, cwd) {
     return
   }
   await copyFile(KNIP_CANONICAL_JSON_PATH, knipPath)
-  passFn('knip.json створено з канонічного npm/rules/js/js/data/tooling/knip-canonical.json (js.mdc)')
+  passFn('knip.json створено з канонічного npm/rules/js/tooling/data/tooling/knip-canonical.json (js.mdc)')
 }
 
 /**

package/rules/js/tooling/data/tooling/knip-canonical.json

@@ -1,6 +1,7 @@
 {
   "$schema": "https://unpkg.com/knip@5/schema.json",
   "entry": [
+    ".pi/extensions/**/*.ts",
     "eslint.config.{js,mjs,cjs}",
     "stylelint.config.{js,cjs,mjs}",
     "oxlint.config.{js,mjs}",

package/rules/js/tooling/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/js/tooling/main.mjs
 docgen:
-  crc: d863fb93
+  crc: da55182a
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/rules/js/tooling/main.mjs

@@ -140,7 +140,7 @@ export function verifyOxlintRcAgainstCanonical(cfg, canonical) {
 
     if (!deepEqualOxlintCanonical(actual, expected)) {
       failures.push(
-        `.oxlintrc.json: поле "${key}" має збігатися з каноном пакета @7n/rules (npm/rules/js/js/data/tooling/oxlint-canonical.json)`
+        `.oxlintrc.json: поле "${key}" має збігатися з каноном пакета @7n/rules (npm/rules/js/tooling/data/tooling/oxlint-canonical.json)`
       )
     }
   }

package/rules/local-ai/main.json

@@ -0,0 +1 @@
+{ "auto": "завжди" }

package/rules/local-ai/main.mdc

@@ -0,0 +1,85 @@
+---
+description: Локальні AI-інструменти на машині розробника — rtk (Rust Token Killer) стискає вивід CLI-команд на 60–90% токенів; агенти застосовують rtk автоматично через hooks, установка лише `brew install rtk-ai/tap/rtk`
+alwaysApply: true
+version: '1.0'
+---
+
+Правило `local-ai` інтегрує локальні AI-інструменти розробника. Зараз покриває **rtk** —
+компресор виводу CLI-команд (тести, git, build: 60–90% економії токенів). Розраховане на
+розширення іншими локальними інструментами в майбутньому.
+
+## Установка (єдиний крок користувача)
+
+```bash
+brew install rtk-ai/tap/rtk
+```
+
+Більше нічого: hook-записи і extension нижче вставляє sync пакета, і всі вони **fail-open** —
+без установленого rtk мовчки пропускають команди без змін. `rtk init` запускати не треба.
+
+## Як агенту користуватись rtk
+
+- Клієнти з rewrite-hook — **Claude Code, Cursor, pi** — переписують shell-команди на
+  rtk-еквіваленти автоматично (див. канонічні записи нижче); робити нічого не треба.
+- Агенти без rewrite-hook (Codex тощо): якщо `command -v rtk` успішний — додавай префікс
+  `rtk` до команд: `rtk git status`, `rtk vitest`, `rtk tsc`, у ланцюжках теж
+  (`rtk git add … && rtk git commit …`). Невідомі rtk команди проходять без змін
+  (passthrough), тож префікс безпечний. Не дублюй префікс для команд, що вже починаються з `rtk`.
+- Разово вимкнути переписування: `RTK_DISABLED=1` в env; запуск без фільтра —
+  `rtk proxy <cmd>`; статистика заощаджень — `rtk gain`.
+
+## Канонічні записи (вставляє sync, коли правило увімкнене)
+
+### `.claude/settings.json` — PreToolUse
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "command -v rtk >/dev/null 2>&1 && exec rtk hook claude; exit 0",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Без rtk hook завершується `exit 0` без виводу — Claude Code виконує команду як є.
+
+### `.cursor/hooks.json` — preToolUse
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "command": "bash -lc 'command -v rtk >/dev/null 2>&1 && exec rtk hook cursor; echo \"{}\"'",
+        "matcher": "Shell",
+        "timeout": 30
+      }
+    ]
+  }
+}
+```
+
+Cursor вимагає JSON-вивід на всіх шляхах — без rtk hook відповідає `{}` (passthrough).
+
+### `.pi/extensions/rtk.ts`
+
+Vendored extension зі складу rtk (`rtk init --agent pi` генерує ідентичний файл у той самий
+шлях — повторна установка ідемпотентна). Тонкий делегат: на `tool_call` bash викликає
+`rtk rewrite <cmd>`; сам вимикається, якщо rtk відсутній або старіший за 0.23.0.
+
+## Вимкнення
+
+`disable-rules: ["local-ai"]` у `.n-rules.json` — наступний sync прибере hook-записи з
+`.claude/settings.json` і `.cursor/hooks.json` та видалить `.pi/extensions/rtk.ts`
+(включно з установленим вручну через `rtk init --agent pi` — шлях спільний).

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

@@ -3,12 +3,12 @@ type: JS Module
 title: sync-claude-config.mjs
 resource: npm/scripts/sync-claude-config.mjs
 docgen:
-  crc: 35cf216c
+  crc: e4513e7a
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 85
 ---
 
-Синхронізує конфігурацію 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-rules.json`. Також зливає фрагмент `.gitignore` з канонічного шаблону, додаючи необхідні записи для ADR.
+Синхронізує конфігурацію 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-rules.json`. Також зливає фрагмент `.gitignore` з канонічного шаблону, додаючи необхідні записи для ADR. За правилом `local-ai` керує rtk-інтеграцією (fail-open, працює лише за наявності бінарника rtk): PreToolUse hook `rtk hook claude` у `.claude/settings.json`, preToolUse entry `rtk hook cursor` у `.cursor/hooks.json` і vendored pi-extension `.pi/extensions/rtk.ts`; вимкнення правила прибирає записи та видаляє extension.
 
 ## Поведінка
 
@@ -22,6 +22,8 @@ ADR_HOOK_COMMAND_MARKER — Визначає маркер шляху до bash-
 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`.
+RTK_CLAUDE_HOOK_COMMAND_MARKER — Визначає маркер rtk PreToolUse hook'а (`rtk hook claude`) у `.claude/settings.json` (правило `local-ai`).
+RTK_CURSOR_HOOK_COMMAND_MARKER — Визначає маркер rtk preToolUse hook'а (`rtk hook cursor`) у `.cursor/hooks.json` (правило `local-ai`).
 MANAGED_HOOK_COMMAND_MARKERS — Містить список усіх маркерів, що ідентифікують керовані хуки пакета.
 PI_DIR — Визначає кореневу директорію для артефактів pi.dev у проєкті-споживачі.
 PI_EXTENSIONS_DIR — Визначає директорію для TS-extensions pi.dev у проєкті-споживачі.
@@ -31,8 +33,8 @@ ADR_GITIGNORE_SNIPPET_REL — Визначає відносний шлях до
 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 за умовою.
+mergeCursorHooksConfig — Зливає конфігурацію `.cursor/hooks.json`, зберігаючи користувацькі записи та додаючи/видаляючи керовані ADR stop entries і rtk preToolUse entry.
+syncCursorHooksConfig — Синхронізує `.cursor/hooks.json` для Cursor Agent hooks, додаючи ADR stop і rtk preToolUse entries за умовою.
 syncClaudeSettings — Синхронізує `.claude/settings.json` за темплейтом, зберігаючи користувацькі налаштування.
 syncAdrHookScript — Копіює канонічний bash-скрипт ADR capture Stop-hook з темплейту пакета у `.claude/hooks/`.
 syncAdrNormalizeHookScript — Копіює канонічний bash-скрипт ADR normalize Stop-hook з темплейту пакета у `.claude/hooks/`.
@@ -40,6 +42,9 @@ syncAdrHookLibScripts — Копіює всі bash-скрипти з `lib/` те
 removeOrphanAdrHookLib — Видаляє директорію `.claude/hooks/lib/` з проєкту, якщо ADR-хуки вимкнені.
 syncPiExtensions — Копіює bundled pi.dev TS-extension `n-rules-adr` у `.pi/extensions/n-rules-adr/` проєкту.
 removeOrphanPiExtension — Видаляє директорію `.pi/extensions/n-rules-adr/` з проєкту, якщо ADR-хуки вимкнені.
+RTK_PI_EXTENSION_FILE — Визначає ім'я файлу rtk pi-extension (`rtk.ts`) — шлях спільний із `rtk init --agent pi`.
+syncRtkPiExtension — Копіює vendored rtk pi-extension у `.pi/extensions/rtk.ts` проєкту (правило `local-ai`).
+removeOrphanRtkPiExtension — Видаляє `.pi/extensions/rtk.ts` з проєкту, якщо правило `local-ai` вимкнене.
 syncGitignoreAdrFragment — Дописує відсутні рядки з канонічного ADR-фрагмента до кореневого `.gitignore` проєкту.
 syncClaudeCommands — Копіює всі slash-команди з `.claude-template/commands/` у `.claude/commands/` проєкту.
 syncClaudeConfig — Виконує повну синхронізацію Claude Code-конфігу, включаючи ADR-хуки, `.gitignore` та pi-extension, залежно від правил.

package/scripts/sync-claude-config.mjs

@@ -18,7 +18,13 @@
  * - `.claude/hooks/normalize-decisions.sh` — fully owned bash-скрипт ADR normalize
  *   Stop-hook (батч-нормалізація чернеток); умови — ті самі, що для `capture`.
  * - `.cursor/hooks.json` — **merge**: користувацькі hooks зберігаються; ADR stop
- *   entries додаються, коли правило `adr` увімкнене, і видаляються, коли вимкнене.
+ *   entries додаються, коли правило `adr` увімкнене, і видаляються, коли вимкнене;
+ *   rtk preToolUse entry — аналогічно за правилом `local-ai`.
+ * - rtk (правило `local-ai`) — fail-open інтеграція компресора виводу CLI-команд:
+ *   PreToolUse hook у `.claude/settings.json` (`rtk hook claude`), preToolUse у
+ *   `.cursor/hooks.json` (`rtk hook cursor`) і vendored pi-extension
+ *   `.pi/extensions/rtk.ts`. Без установленого rtk hooks мовчки пропускають команди,
+ *   тож конфіг безпечно потрапляє в git — установка зводиться до `brew install rtk-ai/tap/rtk`.
  * - `.gitignore` — **merge** (лише з `adr`): дописує відсутні рядки з канонічного
  *   фрагмента `rules/adr/js/hooks/template/.gitignore.snippet` (`node_modules/`, `dist/`,
  *   `*.secret`, логи capture/normalize, `.normalize-state`, `.normalize.lock`,
@@ -52,6 +58,10 @@ export const ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize-decisi
 export const CURSOR_ADR_HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
 /** Маркер Cursor ADR Normalize Stop-hook'а — той самий script path, але в `.cursor/hooks.json`. */
 export const CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize-decisions.sh'
+/** Маркер rtk PreToolUse hook'а у `.claude/settings.json` (правило `local-ai`). */
+export const RTK_CLAUDE_HOOK_COMMAND_MARKER = 'rtk hook claude'
+/** Маркер rtk preToolUse hook'а у `.cursor/hooks.json` (правило `local-ai`). */
+export const RTK_CURSOR_HOOK_COMMAND_MARKER = 'rtk hook cursor'
 /**
  * Усі маркери managed-hook'ів пакета — за ними відрізняємо свої записи від користувацьких.
  * Legacy stop-hook включений сюди, щоб старі entries автоматично видалялись при наступному sync-у.
@@ -65,7 +75,8 @@ export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([
   LEGACY_DOC_FILES_HOOK_COMMAND_MARKER,
   LEGACY_STOP_HOOK_COMMAND_MARKER,
   ADR_HOOK_COMMAND_MARKER,
-  ADR_NORMALIZE_HOOK_COMMAND_MARKER
+  ADR_NORMALIZE_HOOK_COMMAND_MARKER,
+  RTK_CLAUDE_HOOK_COMMAND_MARKER
 ])
 
 const CLAUDE_DIR = '.claude'
@@ -130,6 +141,32 @@ const CURSOR_ADR_STOP_HOOK = Object.freeze({
   timeout: 180
 })
 
+/**
+ * Канонічна група hooks для rtk PreToolUse (правило `local-ai`): переписує Bash-команди
+ * на rtk-еквіваленти. Fail-open guard: без установленого rtk — `exit 0` без виводу,
+ * Claude Code виконує команду без змін.
+ */
+const RTK_PRE_TOOL_USE_HOOK_GROUP = Object.freeze({
+  matcher: 'Bash',
+  hooks: Object.freeze([
+    Object.freeze({
+      type: 'command',
+      command: `command -v rtk >/dev/null 2>&1 && exec ${RTK_CLAUDE_HOOK_COMMAND_MARKER}; exit 0`,
+      timeout: 30
+    })
+  ])
+})
+
+/**
+ * Канонічний Cursor preToolUse hook для rtk (правило `local-ai`). Cursor вимагає JSON-вивід
+ * на всіх code path — без установленого rtk відповідаємо `{}` (passthrough).
+ */
+const CURSOR_RTK_PRE_TOOL_USE_HOOK = Object.freeze({
+  command: `bash -lc 'command -v rtk >/dev/null 2>&1 && exec ${RTK_CURSOR_HOOK_COMMAND_MARKER}; echo "{}"'`,
+  matcher: 'Shell',
+  timeout: 30
+})
+
 /** Канонічний Cursor stop-hook для ADR normalize. */
 const CURSOR_ADR_NORMALIZE_STOP_HOOK = Object.freeze({
   command: [
@@ -188,13 +225,13 @@ function isManagedHookGroup(group) {
 /**
  * Чи Cursor hook entry належить пакету `@7n/rules`.
  * @param {CursorHookEntry} entry один entry з `.cursor/hooks.json`
- * @returns {boolean} `true`, якщо command містить managed ADR marker
+ * @returns {boolean} `true`, якщо command містить managed ADR або rtk marker
  */
 function isManagedCursorHookEntry(entry) {
   return (
     typeof entry?.command === 'string' &&
-    [CURSOR_ADR_HOOK_COMMAND_MARKER, CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER].some(marker =>
-      entry.command.includes(marker)
+    [CURSOR_ADR_HOOK_COMMAND_MARKER, CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER, RTK_CURSOR_HOOK_COMMAND_MARKER].some(
+      marker => entry.command.includes(marker)
     )
   )
 }
@@ -268,16 +305,36 @@ function templateWithAdrHook(template) {
   return { ...template, hooks }
 }
 
+/**
+ * Будує копію темплейту із додатковою rtk PreToolUse hook-групою (правило `local-ai`).
+ * Темплейт залишається незмінним; повертається новий об'єкт з доданою групою.
+ * @param {ClaudeSettings} template вихідний темплейт із `.claude-template/settings.template.json`
+ * @returns {ClaudeSettings} копія з доданою rtk-групою у `hooks.PreToolUse`
+ */
+function templateWithRtkHook(template) {
+  /** @type {Record<string, HookGroup[]>} */
+  const hooks = {}
+  for (const [event, groups] of Object.entries(template.hooks ?? {})) {
+    hooks[event] = Array.isArray(groups) ? [...groups] : []
+  }
+  hooks.PreToolUse = [...(hooks.PreToolUse ?? []), /** @type {HookGroup} */ (RTK_PRE_TOOL_USE_HOOK_GROUP)]
+  return { ...template, hooks }
+}
+
 /**
  * Повертає об'єднаний об'єкт settings.json.
  * @param {ClaudeSettings | undefined} existing існуючий вміст `.claude/settings.json` користувача (або undefined, якщо файла нема)
  * @param {ClaudeSettings} template settings із темплейту пакета `@7n/rules`
  * @param {object} [options] опції merge-у
  * @param {boolean} [options.includeAdrHook] чи додати ADR Stop-hook групу до managed-hooks (коли в `.n-rules.json` `rules` присутнє `adr`)
+ * @param {boolean} [options.includeLocalAiHook] чи додати rtk PreToolUse-групу (коли в `.n-rules.json` `rules` присутнє `local-ai`)
  * @returns {ClaudeSettings} результат merge-у (користувацькі поля збережено, наші перевизначено)
  */
 export function mergeSettings(existing, template, options = {}) {
-  const effectiveTemplate = options.includeAdrHook ? templateWithAdrHook(template) : template
+  let effectiveTemplate = options.includeAdrHook ? templateWithAdrHook(template) : template
+  if (options.includeLocalAiHook) {
+    effectiveTemplate = templateWithRtkHook(effectiveTemplate)
+  }
   /** @type {ClaudeSettings} */
   const merged = { ...existing }
   const mergedAllow = mergeAllowList(existing?.permissions?.allow, effectiveTemplate.permissions?.allow)
@@ -295,10 +352,12 @@ export function mergeSettings(existing, template, options = {}) {
 
 /**
  * Зливає `.cursor/hooks.json`: користувацькі entries зберігаються, managed ADR
- * entries у `hooks.stop` перезаписуються або видаляються залежно від `includeAdrHook`.
+ * entries у `hooks.stop` перезаписуються або видаляються залежно від `includeAdrHook`;
+ * managed rtk entry у `hooks.preToolUse` — залежно від `includeLocalAiHook`.
  * @param {CursorHooksConfig | undefined} existing поточний Cursor hooks config
  * @param {object} [options] опції merge-у
  * @param {boolean} [options.includeAdrHook] чи додати ADR stop entries
+ * @param {boolean} [options.includeLocalAiHook] чи додати rtk preToolUse entry
  * @returns {CursorHooksConfig} результат злиття
  */
 export function mergeCursorHooksConfig(existing, options = {}) {
@@ -321,6 +380,15 @@ export function mergeCursorHooksConfig(existing, options = {}) {
   } else {
     delete hooks.stop
   }
+  const preToolUse = (hooks.preToolUse ?? []).filter(entry => !isManagedCursorHookEntry(entry))
+  if (options.includeLocalAiHook) {
+    preToolUse.push(/** @type {CursorHookEntry} */ (CURSOR_RTK_PRE_TOOL_USE_HOOK))
+  }
+  if (preToolUse.length > 0) {
+    hooks.preToolUse = preToolUse
+  } else {
+    delete hooks.preToolUse
+  }
   merged.version = typeof merged.version === 'number' ? merged.version : 1
   if (Object.keys(hooks).length > 0) {
     merged.hooks = hooks
@@ -347,17 +415,18 @@ async function readJsonOrUndefined(path) {
 }
 
 /**
- * Синхронізує `.cursor/hooks.json` для Cursor Agent stop-hooks. Cursor читає
- * project-level config з `.cursor/hooks.json`; hook scripts лишаються спільними
- * з Claude Code у `.claude/hooks/`.
+ * Синхронізує `.cursor/hooks.json` для Cursor Agent hooks (ADR stop + rtk preToolUse).
+ * Cursor читає project-level config з `.cursor/hooks.json`; hook scripts лишаються
+ * спільними з Claude Code у `.claude/hooks/`.
  * @param {string} projectRoot корінь проєкту, куди писати
  * @param {object} [options] опції merge-у
  * @param {boolean} [options.includeAdrHook] чи додавати ADR stop-hook entries
+ * @param {boolean} [options.includeLocalAiHook] чи додавати rtk preToolUse entry
  * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
 export async function syncCursorHooksConfig(projectRoot, options = {}) {
   const hooksPath = join(projectRoot, CURSOR_HOOKS_FILE)
-  if (!options.includeAdrHook && !existsSync(hooksPath)) {
+  if (!options.includeAdrHook && !options.includeLocalAiHook && !existsSync(hooksPath)) {
     return { written: false, path: '' }
   }
   const existing = /** @type {CursorHooksConfig | undefined} */ (await readJsonOrUndefined(hooksPath))
@@ -539,6 +608,44 @@ export async function removeOrphanPiExtension(projectRoot) {
   return { removed: true, path: `${PI_EXTENSIONS_DIR}/${PI_EXTENSION_NAME}` }
 }
 
+/** Ім'я файлу rtk pi-extension — той самий шлях, що пише `rtk init --agent pi` (повторна установка ідемпотентна). */
+export const RTK_PI_EXTENSION_FILE = 'rtk.ts'
+
+/**
+ * Копіює vendored rtk pi-extension `npm/.pi-template/extensions/rtk.ts` у
+ * `.pi/extensions/rtk.ts` проєкту-споживача (правило `local-ai`). Файл fully-owned:
+ * при кожному sync-у перезаписується. Якщо bundled template відсутній — `{written: false}`.
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} bundledPackageRoot корінь установленого `@7n/rules` (із `.pi-template/`)
+ * @returns {Promise<{ written: boolean, path: string }>} чи писали та відносний шлях файла
+ */
+export async function syncRtkPiExtension(projectRoot, bundledPackageRoot) {
+  const srcPath = join(bundledPackageRoot, PI_TEMPLATE_DIR_NAME, 'extensions', RTK_PI_EXTENSION_FILE)
+  if (!existsSync(srcPath)) {
+    return { written: false, path: '' }
+  }
+  const destDir = join(projectRoot, PI_EXTENSIONS_DIR)
+  await mkdir(destDir, { recursive: true })
+  await writeFile(join(destDir, RTK_PI_EXTENSION_FILE), await readFile(srcPath, 'utf8'), 'utf8')
+  return { written: true, path: `${PI_EXTENSIONS_DIR}/${RTK_PI_EXTENSION_FILE}` }
+}
+
+/**
+ * Видаляє `.pi/extensions/rtk.ts` з проєкту-споживача. Викликається, коли правило
+ * `local-ai` вимкнено у `.n-rules.json` (симетрично до cleanup-у hook-записів).
+ * Шлях спільний з `rtk init --agent pi`, тож прибереться і встановлений вручну файл.
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @returns {Promise<{ removed: boolean, path: string }>} чи було щось видалено та відносний шлях
+ */
+export async function removeOrphanRtkPiExtension(projectRoot) {
+  const extPath = join(projectRoot, PI_EXTENSIONS_DIR, RTK_PI_EXTENSION_FILE)
+  if (!existsSync(extPath)) {
+    return { removed: false, path: '' }
+  }
+  await rm(extPath, { force: true })
+  return { removed: true, path: `${PI_EXTENSIONS_DIR}/${RTK_PI_EXTENSION_FILE}` }
+}
+
 /**
  * Повертає змістовні (не коментар, не порожній) рядки з text-фрагмента `.gitignore`.
  * @param {string} raw вміст snippet-файлу
@@ -627,36 +734,30 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
  * @param {string} options.projectRoot корінь проєкту-споживача
  * @param {string} options.bundledPackageRoot корінь установленого `@7n/rules`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-rules.json` `claude-config`)
- * @param {string[]} [options.rules] список увімкнених правил із `.n-rules.json` — впливає на ADR Stop-hook (`adr`)
- * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, adrHookLib: string[], gitignoreAdr: boolean, piExtension: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore`/pi-extension, перелік lib-файлів і список slash-команд
+ * @param {string[]} [options.rules] список увімкнених правил із `.n-rules.json` — впливає на ADR Stop-hook (`adr`) і rtk hooks (`local-ai`)
+ * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, adrHookLib: string[], gitignoreAdr: boolean, piExtension: boolean, rtkPiExtension: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore`/pi-extension(s), перелік lib-файлів і список slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
+  const noop = {
+    settings: false,
+    cursorHooks: false,
+    commands: [],
+    adrHook: false,
+    adrNormalizeHook: false,
+    adrHookLib: [],
+    gitignoreAdr: false,
+    piExtension: false,
+    rtkPiExtension: false
+  }
   if (!enabled) {
-    return {
-      settings: false,
-      cursorHooks: false,
-      commands: [],
-      adrHook: false,
-      adrNormalizeHook: false,
-      adrHookLib: [],
-      gitignoreAdr: false,
-      piExtension: false
-    }
+    return noop
   }
   const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
   if (!existsSync(templateDir)) {
-    return {
-      settings: false,
-      cursorHooks: false,
-      commands: [],
-      adrHook: false,
-      adrNormalizeHook: false,
-      adrHookLib: [],
-      gitignoreAdr: false,
-      piExtension: false
-    }
+    return noop
   }
   const includeAdrHook = Array.isArray(rules) && rules.includes('adr')
+  const includeLocalAiHook = Array.isArray(rules) && rules.includes('local-ai')
   const adrHook = includeAdrHook ? await syncAdrHookScript(projectRoot, templateDir) : { written: false, path: '' }
   const adrNormalizeHook = includeAdrHook
     ? await syncAdrNormalizeHookScript(projectRoot, templateDir)
@@ -676,8 +777,15 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
     const removed = await removeOrphanPiExtension(projectRoot)
     piExtension = { written: false, path: removed.path }
   }
-  const settings = await syncClaudeSettings(projectRoot, templateDir, { includeAdrHook })
-  const cursorHooks = await syncCursorHooksConfig(projectRoot, { includeAdrHook })
+  let rtkPiExtension
+  if (includeLocalAiHook) {
+    rtkPiExtension = await syncRtkPiExtension(projectRoot, bundledPackageRoot)
+  } else {
+    const removed = await removeOrphanRtkPiExtension(projectRoot)
+    rtkPiExtension = { written: false, path: removed.path }
+  }
+  const settings = await syncClaudeSettings(projectRoot, templateDir, { includeAdrHook, includeLocalAiHook })
+  const cursorHooks = await syncCursorHooksConfig(projectRoot, { includeAdrHook, includeLocalAiHook })
   const commands = await syncClaudeCommands(projectRoot, templateDir)
   return {
     settings: settings.written,
@@ -687,6 +795,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
     adrNormalizeHook: adrNormalizeHook.written,
     adrHookLib: adrHookLibEntries.map(e => e.path),
     gitignoreAdr: gitignoreAdr.written,
-    piExtension: piExtension.written
+    piExtension: piExtension.written,
+    rtkPiExtension: rtkPiExtension.written
   }
 }