@nitra/cursor 12.3.1 → 12.3.3

package/.claude-template/hooks/capture-decisions.sh

@@ -91,26 +91,38 @@ if [[ -z "$TRANSCRIPT" ]]; then
   exit 0
 fi
 
+# Файли, змінені в сесії (file_path із tool_use Edit/Write/MultiEdit) — спільне
+# джерело для structural-скіпів нижче.
+CHANGED_FILES=$(jq -r '
+  select(.type == "assistant" or .role == "assistant")
+  | .message as $m
+  | ($m.content // [])
+  | if type == "array" then
+      map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
+          | .input.file_path // empty)
+      | .[]
+    else empty end
+' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || true)
+
+# Cross-project skip: якщо в сесії редагувалися файли, але ЖОДЕН не під $PROJECT_ROOT —
+# це паралельна робота в іншому проєкті; ADR сюди не пишемо (чужі рішення не змішуємо).
+# Сесії без редагувань (чисте Q&A / дизайн-дискусія) не відкидаємо — це валідний ADR.
+# ENV `ADR_CAPTURE_SKIP_CROSS_PROJECT=0` вимикає скіп.
+if [[ "${ADR_CAPTURE_SKIP_CROSS_PROJECT:-1}" = "1" && -n "$CHANGED_FILES" ]]; then
+  if ! printf '%s\n' "$CHANGED_FILES" | has_in_project_change "$PROJECT_ROOT"; then
+    log "  → skipping ADR capture: cross-project session (no in-project changes)"
+    log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
+    exit 0
+  fi
+fi
+
 # Structural skip: якщо в сесії змінювалися лише tooling-файли — не викликаємо LLM.
 # ENV `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0` вимикає скіп.
-if [[ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" ]]; then
-  CHANGED_FILES=$(jq -r '
-    select(.type == "assistant" or .role == "assistant")
-    | .message as $m
-    | ($m.content // [])
-    | if type == "array" then
-        map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
-            | .input.file_path // empty)
-        | .[]
-      else empty end
-  ' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || true)
-
-  if [[ -n "$CHANGED_FILES" ]]; then
-    if printf '%s\n' "$CHANGED_FILES" | is_tooling_only_change "$PROJECT_ROOT"; then
-      log "  → skipping ADR capture: tooling-only session"
-      log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
-      exit 0
-    fi
+if [[ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" && -n "$CHANGED_FILES" ]]; then
+  if printf '%s\n' "$CHANGED_FILES" | is_tooling_only_change "$PROJECT_ROOT"; then
+    log "  → skipping ADR capture: tooling-only session"
+    log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
+    exit 0
   fi
 fi
 
@@ -166,7 +178,12 @@ TRANSCRIPT FOLLOWS:
 EOF
 )
 
-PROMPT_FULL=$(printf '%s\n%s\n' "$PROMPT" "$TRANSCRIPT")
+# Scope: обмежуємо рішення поточним проєктом. Для змішаних сесій (правки і тут, і в
+# чужих репо) детермінований cross-project gate не спрацьовує, тож звужуємо обсяг у промпті.
+# Йде ПЕРЕД інструкціями, щоб не сприйматись як перший рядок транскрипту.
+SCOPE_LINE="CURRENT PROJECT ROOT: $PROJECT_ROOT
+SCOPE: Document ONLY decisions evidenced by changes within this project root. Ignore edits and discussion about files outside it (parallel work in other repositories)."
+PROMPT_FULL=$(printf '%s\n\n%s\n%s\n' "$SCOPE_LINE" "$PROMPT" "$TRANSCRIPT")
 
 CLAUDE_MODEL="${CAPTURE_DECISIONS_CLAUDE_MODEL:-sonnet}"
 CURSOR_MODEL="${CAPTURE_DECISIONS_CURSOR_MODEL:-claude-4.6-sonnet-medium}"

package/.claude-template/hooks/lib/tooling-only.sh

@@ -39,6 +39,22 @@ is_tooling_only_change() {
   return 1
 }
 
+# Cross-project guard: чи серед змінених файлів є хоч один під $proj.
+# Вхід: рядки-шляхи у stdin (абсолютні file_path із tool_use).
+# Вихід: 0 — є хоч один файл під $proj; 1 — жодного (сесія цілком в інших проєктах).
+# Призначення: відсікти ADR-чернетки від паралельної роботи в чужих репозиторіях.
+has_in_project_change() {
+  local proj="$1"
+  local f
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    case "$f" in
+      "$proj"/*) return 0 ;;
+    esac
+  done
+  return 1
+}
+
 # Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
 # Поза git-репо або при помилці — вертаємо 1 (не tooling).
 git_diff_only_version_field() {

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [12.3.3] - 2026-06-20
+
+### Changed
+
+- ♻️ refactor(pipeline): Оновлено логіку ADR-захоплення та цілісність збірки
+
+## [12.3.2] - 2026-06-20
+
+### Fixed
+
+- fix-каскад: per-tier timeout (локалі fail-fast ~45s замість стіни 120s, env N_LOCAL_FIX_TIMEOUT_MS/N_CLOUD_FIX_TIMEOUT_MS) + хмарний транспортний збій (pi ETIMEDOUT/spawn) обриває драбину замість ескалації на cloud-avg — не палиться avg-бюджет
+
 ## [12.3.1] - 2026-06-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.3.1",
+  "version": "12.3.3",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/bun/bun.mdc

@@ -66,10 +66,10 @@ FROM oven/bun:alpine AS build-env
 
 ## lint
 
-Якщо в кореневому @package.json  існують скрипти з префіксом `lint-`, обов'язково створюй `lint` скрипт, який буде запускати всі ці скрипти з лінт-префіксом.
+Лінт запускається через CLI **`n-cursor`**, **не** через `package.json`-скрипти:
 
-У кінці скрипта `lint` додай `&& oxfmt .`.
+- **`n-cursor lint --full`** — весь репо: усі правила (per-file лінтери + конформність) + `oxfmt` у кінці (fix-режим);
+- **`n-cursor lint`** — дельта vs origin (per-file лінтери лише змінених файлів);
+- **`n-cursor lint <rule…>`** — конкретні правила (лінтер + конформність), напр. **`n-cursor lint ga`**.
 
-Якщо в **`.n-cursor.json`** у масиві **`rules`** є **`docker`**, у кореневому `package.json` **обов'язково** скрипт **`lint-docker`** (див. **`docker.mdc`**) і рядок **`bun run lint-docker`** у **`lint`**. Якщо є **`k8s`** — **обов'язково** **`lint-k8s`** і **`bun run lint-k8s`** у **`lint`** (див. **`k8s.mdc`**).
-
-**Зворотній інваріант:** якщо правила **немає** в `rules` (або воно явно перенесене в **`disable-rules`**), скрипту **`lint-<id>`** у кореневому `package.json` бути **не може**, і ланцюжок агрегованого **`scripts.lint`** не має містити **`bun run lint-<id>`**. Інакше `bun run lint` падатиме на вимкненому правилі — `n-cursor lint-<id>` ігнорує `.n-cursor.json` і обходить дерево незалежно від `rules`/`disable-rules`. Для скриптів із кількома власниками (як **`lint-image`** — обслуговує і **`image-avif`**, і **`image-compress`**) скрипт лишається дозволеним, поки активний **хоч один** власник; зворотній інваріант тригериться лише коли в `rules` немає **жодного** з них. Перевірка — **`npx @nitra/cursor fix bun`**.
+У кореневому `package.json` **не повинно бути** `lint`/`lint-*` скриптів — єдина точка лінту — CLI `n-cursor`. У CI кожен workflow викликає **`n-cursor lint <rule> --read-only`** напряму (без обгорток).

package/rules/bun/policy/package_json/package_json.rego

@@ -8,7 +8,6 @@
 #  - `devDependencies` лише `@nitra/*` + root-only тестові peer/tools для `n-cursor coverage`
 #    (правило `test` enabled завжди — див. `test/auto.md`; published workspace-и не мають
 #     `devDependencies` за `npm-module.mdc`)
-#  - Агрегований `lint` скрипт (cross-script aggregation logic)
 #
 # Перевірки, які ЗАЛИШИЛИСЬ у JS (потребують FS / cross-file):
 #  - `lint-docker` / `lint-k8s` коли `.n-cursor.json:rules` містить відповідне
@@ -17,13 +16,6 @@ package bun.package_json
 
 import rego.v1
 
-# ── Шаблони повідомлень ────────────────────────────────────────────────────
-
-lint_aggregate_missing_template := concat(" ", [
-	"У package.json є скрипти %v, але немає агрегованого `lint`.",
-	"Додай скрипт, який запускає їх через `bun run` (bun.mdc)",
-])
-
 # ── deny: заборонені top-level поля (template-driven) ─────────────────────
 
 # Сентинельний value відрізняє «поле відсутнє» від «поле є з будь-яким значенням»
@@ -43,29 +35,6 @@ deny contains msg if {
 	msg := sprintf("Кореневі devDependencies: дозволені лише @nitra/* або root-only test peers — прибери або перенеси: %s (bun.mdc)", [name])
 }
 
-# ── deny: агрегований lint-скрипт (cross-script aggregation logic) ───────
-
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script == ""
-	msg := sprintf(lint_aggregate_missing_template, [lint_prefixed_scripts])
-}
-
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script != ""
-	some script in lint_prefixed_scripts
-	not contains(lint_script, sprintf("bun run %s", [script]))
-	msg := sprintf("Скрипт `lint` має викликати `%s` через `bun run` (bun.mdc)", [script])
-}
-
-deny contains msg if {
-	count(lint_prefixed_scripts) > 0
-	lint_script != ""
-	not regex.match(`&&[ \t]+oxfmt[ \t]+\.[ \t]*$`, lint_script)
-	msg := "Скрипт `lint` має закінчуватися на `&& oxfmt .` (bun.mdc)"
-}
-
 # ── helpers ────────────────────────────────────────────────────────────────
 
 allowed_root_test_deps := {"vitest", "@vitest/coverage-v8", "@stryker-mutator/vitest-runner", "@playwright/test"}

package/rules/ga/ga.mdc

@@ -118,11 +118,9 @@ concurrency:
       - uses: ./.github/actions/setup-bun-deps
 ```
 
-**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Канонічний скрипт у корені делегує виконання CLI `n-cursor lint-ga` (бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`:
+**Лінт:** [actionlint](https://github.com/rhysd/actionlint) через [github-actionlint](https://www.npmjs.com/package/github-actionlint); [zizmor](https://docs.zizmor.sh) — `uvx`, офлайн. Запуск — через **`n-cursor lint ga`** (CI — `--read-only`; бінарка з `node_modules/.bin/` пакету `@nitra/cursor`), який робить preflight на `shellcheck` і послідовно запускає `actionlint` та `zizmor`. Окремого `package.json`-скрипта немає.
 
-- `package.json` — `scripts.lint-ga` має містити `n-cursor lint-ga`: [package.json.contains.json](./policy/package_json/template/package.json.contains.json)
-
-> Не використовуй `npx --no @nitra/cursor lint-ga` — `bun run` автоматично транслює `npx` у `bun x`, а `bun x` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання. Виклик через bin-ім’я `n-cursor` працює і у `bun run`, і у `npm run`.
+> Виклик через bin-ім’я `n-cursor` (а **не** `npx @nitra/cursor`): `bun x`/`npx` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання, тому в CI-кроці `run:` використовуй саме `n-cursor lint <rule>`.
 
 CLI робить preflight на `shellcheck` і `uv` (`uvx`) у `PATH`, потім запускає `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
 

package/rules/ga/policy/lint_ga/lint_ga.rego

@@ -100,8 +100,8 @@ deny contains msg if {
 
 deny contains msg if {
 	expected_run_blob != ""
-	not contains(job_run_blob, "bun run lint-ga")
-	msg := "lint-ga.yml: має бути крок run: bun run lint-ga (ga.mdc)"
+	not contains(job_run_blob, "n-cursor lint ga --read-only")
+	msg := "lint-ga.yml: має бути крок run: n-cursor lint ga --read-only (ga.mdc)"
 }
 
 # ── helpers ────────────────────────────────────────────────────────────────

package/rules/ga/policy/lint_ga/template/lint-ga.yml.snippet.yml

@@ -38,4 +38,4 @@ jobs:
           | sudo tar -xz -C /usr/local/bin conftest
 
       - name: Lint GA
-        run: bun run lint-ga
+        run: n-cursor lint ga --read-only

package/rules/js-lint/js-lint.mdc

@@ -5,23 +5,20 @@ alwaysApply: false
 version: '1.30'
 ---
 
-**oxlint**, **ESLint**, **jscpd**, **knip**. У скрипті **`lint-js`** і в CI — **`bunx oxlint`**, **`bunx eslint`**, **`bunx jscpd`**, **`bunx knip`** (у CI без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
+**oxlint**, **ESLint**, **jscpd**, **knip**. Запуск — **`n-cursor lint js-lint js-lint-ci`** (локально; у CI — `--read-only`, без **`--fix`** для oxlint/eslint — див. приклад workflow нижче). Без **prettier** і **@nitra/prettier-config**. У **`devDependencies`** має бути **`@nitra/eslint-config`** — версія не нижче канонічного мінімуму зі snippet нижче (semver-поріг, єдине джерело істини) (з **3.8.0** правило `no-restricted-syntax` забороняє `for...in`; з **3.9.2** у `getConfig` вбудовано ignore для **`**/adr/**`** — ADR-документи не валідуються ESLint, локально цей glob додавати не потрібно; також транзитивно йде **`@e18e/eslint-plugin`** для oxlint). Dependency-політику CI-етапу (`@e18e/eslint-plugin` і oxlint/eslint/jscpd/knip окремо не додавати) винесено в `js-lint-ci`.
 
 У кожному **`package.json`** проєкту (корінь і всі workspace-пакети) має бути **`"type": "module"`** — весь код у ESM.
 
 ```json title="package.json"
 {
   "type": "module",
-  "scripts": {
-    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
-  },
   "devDependencies": {
     "@nitra/eslint-config": "^3.10.0"
   }
 }
 ```
 
-Канон `type` + `scripts.lint-js` (substring requirement) і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
+Канон `type` і мінімальна `@nitra/eslint-config` (semver-поріг `devDependencies`): [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json). Окремого `lint-js` скрипта немає — лінт через **`n-cursor lint js-lint js-lint-ci`** (CI — `--read-only`).
 
 ## Розширення нових файлів — `.mjs` / `.cjs`, не `.js`
 

package/rules/js-lint/policy/lint_js_yml/template/lint-js.yml.snippet.yml

@@ -37,8 +37,4 @@ jobs:
       - uses: ./.github/actions/setup-bun-deps
 
       - name: Eslint
-        run: |
-          bunx oxlint
-          bunx eslint .
-          bunx jscpd .
-          bunx knip --no-config-hints
+        run: n-cursor lint js-lint js-lint-ci --read-only

package/rules/js-lint/policy/package_json/template/package.json.snippet.json

@@ -1,8 +1,5 @@
 {
   "type": "module",
-  "scripts": {
-    "lint-js": "bunx oxlint --fix && bunx eslint --fix . && bunx jscpd . && bunx knip --no-config-hints"
-  },
   "devDependencies": {
     "@nitra/eslint-config": "^3.10.0"
   }

package/rules/lint/js/docs/orchestrate.md

@@ -3,30 +3,29 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: 0ab5b22c
+  crc: b0c7a4c2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Оркестратор `n-cursor lint` визначає, які правила лінтування застосовувати, керуючись двома ортогональними осями: консолідацією правил та уніфікацією режиму `readonly`. Вибір правил відбувається на основі конфігурацій, зокрема файлів `meta.json`, які визначають обсяг дії (`per-file` чи `full`) для кожного правила. Запуск лінтування може сканувати лише змінені файли відносно origin (за замовчуванням) або весь репозиторій при використанні прапорця `--full`.
+## Огляд
+
+Модуль відповідає за визначення та виконання процесу лінтування коду. Функція `selectLintRules` вибирає та сортує ідентифікатори правил лінтування на основі конфігурацій, визначених у meta.json. Функція `runLint` запускає перевірку обраних правил для змінених або всіх файлів репозиторію.
 
 ## Поведінка
 
-Поведінка
-selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
-runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах (`runPerFileRules`), запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
-**Fail-fast — лише в `--read-only`** (CI/детект): перший ненульовий код спиняє. У fix-режимі (default) ненульовий код per-file правила НЕ спиняє — проганяються всі правила й виконується крок виправлення (конформність-драбина), а повертається найгірший код.
-У режимі `--full` без `--read-only` після конформність-фази (`runFullConformancePhase`) друкується резюме викликів моделей за прогін (`reportRunStats`: локальна / cloud-min / cloud-avg) і викликається escalation-аналітика (`analyze-escalation.mjs`): фіксує зсув escalation-логу до фази, після — аналізує записи саме цього прогону. Жодне з цього не впливає на exit-код lint.
+selectLintRules вибирає і сортує ідентифікатори правил для лінтування на основі їхніх конфігурацій, включаючи можливість включення правил, що застосовуються до всього репозиторію.
+runLint запускає процес лінтування, виконуючи перевірку правил для змінених файлів або для всього репозиторію, залежно від наданих опцій, і може виконувати форматування.
 
 ## Публічний API
 
-selectLintRules — Вибирає ідентифікатори правил для контексту в алфавітному порядку.
+selectLintRules — Вибирає ідентифікатори правил для контексту, упорядковані за алфавітом.
 runLint — Запускає процес лінтування.
-  full — Сканує весь репозиторій порівняно з початковим станом.
+  full — Сканує весь репозиторій, порівнюючи його з початковим станом.
   readOnly — Виявляє проблеми без внесення змін.
-  rules — Перевіряє лише відповідність заданого набору правил, ігноруючи повне сканування.
+  rules — Виконує повне сканування лише для вказаних правил у заданому обсязі.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/lint/js/orchestrate.mjs

@@ -3,9 +3,11 @@ import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { cwd as processCwd } from 'node:process'
+import { spawnSync } from 'node:child_process'
 
 import { parseRuleLintSpec, readRuleMetaRaw } from '../../../scripts/lib/rule-meta.mjs'
 import { collectChangedFilesSince, resolveChangedBase } from '../../../scripts/lib/changed-files.mjs'
+import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 
 // Цей файл: npm/rules/lint/js/orchestrate.mjs → PACKAGE_ROOT = npm (чотири dirname угору).
 const PACKAGE_ROOT = dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url)))))
@@ -120,12 +122,62 @@ async function runFullConformancePhase(cwd, readOnly, log) {
   return conformanceCode
 }
 
+/**
+ * Формат-крок (`oxfmt .`): whole-tree форматування у fix-режимі. У read-only НЕ викликається
+ * (CI/детект — нуль мутацій). `oxfmt` форматує не лише JS, а й root-конфіги (toml тощо), тож
+ * крок незалежний від набору правил і scope. Якщо `oxfmt` відсутній у PATH — пропуск (не fail).
+ * @param {string} cwd корінь
+ * @param {(s: string) => void} log логер
+ * @returns {Promise<number>} код виходу oxfmt (0 — OK або пропущено)
+ */
+async function runFormat(cwd, log) {
+  const oxfmt = resolveCmd('oxfmt')
+  if (!oxfmt) {
+    log('ℹ️  lint: oxfmt недоступний у PATH — формат-крок пропущено.\n')
+    return 0
+  }
+  const r = spawnSync(oxfmt, ['.'], { cwd, stdio: 'inherit', shell: false })
+  const code = typeof r.status === 'number' ? r.status : 1
+  if (code !== 0) log(`❌ lint: oxfmt — помилка (код ${code})\n`)
+  return code
+}
+
+/**
+ * Scoped-режим (`lint <rule…>`): повний прогін НАЗВАНИХ правил — їх лінтер (`js/lint.mjs`,
+ * whole-repo) для тих, що його мають, + конформність для всіх названих. Дзеркалить `--full`,
+ * але звужено до правил, тож `lint ga` ≡ standalone `lint-ga`. Конформність-only правила
+ * (напр. `changelog` із hk) не мають `js/lint.mjs` → проганяється лише їх конформність
+ * (зворотна сумісність із колишнім `fix <rule>`). oxfmt у scoped НЕ запускається — це
+ * таргетований прогін правил, а не глобальне форматування.
+ * @param {string[]} rules id названих правил
+ * @param {{ cwd: string, readOnly: boolean, rulesDir: string, conformance: boolean, log: (s: string) => void }} ctx контекст (`conformance` — чи запускати конформність; false для юніт-тестів із кастомним rulesDir, де реальний пакет недоступний)
+ * @returns {Promise<number>} найгірший код (read-only — fail-fast на першому ненульовому)
+ */
+async function runScopedRules(rules, ctx) {
+  const { cwd, readOnly, rulesDir, conformance, log } = ctx
+  const metaById = readAllMeta(rulesDir)
+  const linterIds = rules.filter(id => existsSync(join(rulesDir, id, 'js', 'lint.mjs')))
+  let worst = 0
+  if (linterIds.length > 0) {
+    const perFile = await runPerFileRules(linterIds, { rulesDir, changed: undefined, cwd, readOnly, metaById, log })
+    if (perFile.stop) return perFile.code
+    worst = perFile.code
+  }
+  if (!conformance) return worst
+  const conformanceCode = await runConformance(cwd, readOnly, log, rules)
+  if (conformanceCode !== 0) {
+    if (readOnly) return conformanceCode
+    worst = conformanceCode
+  }
+  return worst
+}
+
 /**
  * Запускає lint-оркестрацію.
  * @param {{ full?: boolean, readOnly?: boolean, rules?: string[], cwd?: string, rulesDir?: string, log?: (s: string) => void }} [opts] параметри
  *   - `full` — весь репо (`true`) проти дельти vs origin (`false`, default);
  *   - `readOnly` — лише детект без мутацій (`true`) проти fix (`false`, default);
- *   - `rules` — непорожній фільтр → лише конформність цих правил (без лінтер-скану; мапить `fix <rule>`).
+ *   - `rules` — непорожній scope → повний прогін лише цих правил (лінтер + конформність, whole-repo).
  * @returns {Promise<number>} exit code
  */
 export async function runLint(opts = {}) {
@@ -136,9 +188,9 @@ export async function runLint(opts = {}) {
   const rulesDir = opts.rulesDir ?? RULES_DIR
   const log = opts.log ?? (s => process.stdout.write(s))
 
-  // Rule-filter режим (напр. `lint changelog` із hk): лише конформність указаних правил, без лінтерів.
+  // Scoped режим (`lint <rule…>`): повний прогін названих правил — лінтер + конформність.
   if (rules.length > 0) {
-    return runConformance(cwd, readOnly, log, rules)
+    return runScopedRules(rules, { cwd, readOnly, rulesDir, conformance: opts.rulesDir === undefined, log })
   }
 
   // Default scope — дельта vs origin (merge-base main/origin/main); `--full` — весь репо.
@@ -163,5 +215,12 @@ export async function runLint(opts = {}) {
       worst = conformanceCode
     }
   }
+
+  // Формат-крок (oxfmt): fix-режим — завжди (будь-який scope); read-only пропускаємо (нуль
+  // мутацій). Кастомний rulesDir (юніт-тести) — реальний пакет недоступний, тож пропускаємо.
+  if (!readOnly && opts.rulesDir === undefined) {
+    const fmtCode = await runFormat(cwd, log)
+    if (fmtCode !== 0) worst = fmtCode
+  }
   return worst
 }

package/rules/python/js/docs/index.md

@@ -9,4 +9,5 @@ resource: npm/rules/python/js/
 | Файл | Тип |
 |---|---|
 | [applies.mjs](applies.md) | JS Module |
+| [lint.mjs](lint.md) | JS Module |
 | [tooling.mjs](tooling.md) | JS Module |

package/rules/python/js/docs/lint.md

@@ -0,0 +1,21 @@
+---
+type: JS Module
+title: lint.mjs
+resource: npm/rules/python/js/lint.mjs
+docgen:
+  crc: a0d17a44
+  score: 100
+---
+
+Оркестраторний адаптер правила `python` для `n-cursor lint`. Делегує перевірку наявній CLI-формі (`runLintPython` із `../lint/lint.mjs`). Режиму на рівні окремих файлів немає — `uv`/`ruff`/`mypy` працюють по всьому проєкту, тож параметр `files` ігнорується. За відсутності `pyproject.toml` у корені крок завершується успіхом без запуску інструментів.
+
+## Поведінка
+
+1. Викликає CLI-форму python-лінтера для всього проєкту.
+2. У `readOnly` пробрасує прапорець далі: `ruff` без `--fix`, `ruff format --check` (нуль мутацій для CI).
+3. Повертає код виходу інструменту.
+
+## Гарантії поведінки
+
+- Read-only за наявності `readOnly`: інструменти не мутують робоче дерево.
+- Не звертається до мережі (uv-кроки можуть, але це поведінка делегата, не цього модуля).

package/rules/python/js/lint.mjs

@@ -0,0 +1,14 @@
+/** @see ./docs/lint.md */
+import { runLintPython } from '../lint/lint.mjs'
+
+/**
+ * Ci-крок python: делегує у наявний CLI правила (per-file режиму немає — `files` ігнорується;
+ * uv/ruff/mypy працюють по всьому проєкту). Без `pyproject.toml` крок — no-op (exit 0).
+ * @param {string[] | undefined} _files ігнорується (whole-project аналіз)
+ * @param {string} [_cwd] корінь (CLI бере process.cwd())
+ * @param {{ readOnly?: boolean }} [opts] readOnly → ruff без `--fix`, format `--check` (нуль мутацій)
+ * @returns {Promise<number>} exit code
+ */
+export function lint(_files, _cwd, opts = {}) {
+  return runLintPython({ readOnly: opts.readOnly === true })
+}