@7n/rules 1.25.1 → 1.27.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [1.27.0] - 2026-07-19
+
+### Added
+
+- LLM-ladder: окремий (більший) таймаут cloud-avg (N_CLOUD_AVG_FIX_TIMEOUT_MS, дефолт 180s) та concern-рівневий skipLocalTier (concern.json) — пропуск local-min/local-min-retry для concern-ів, де local-tier емпірично не встигає дати результат (js/eslint увімкнено за реальними даними прогону)
+
+### Changed
+
+- doc-files: ядро без вбудованих кодових розширень (фаза 5b spec lang-plugins-extraction) — перелік розширень, OKF-типи та мовні екстрактори (факти/юніти) приходять лише з декларацій активних lang-плагінів (contributes.docFiles.extensions + handler doc-files); JS-специфіка (extractFacts, units-js, мапа типів js/mjs/ts/vue) переїхала у @7n/rules-lang-js; без активного lang-плагіна скан не бачить джерел (graceful тиша)
+
+### Fixed
+
+- Червоний lint на main: дубльовані тести мосту auto-worktree (auto-worktree.test.mjs ↔ orchestrate.test.mjs) зібрано у спільний набір `describeAutoWorktreeBridge` (scripts/utils/tests/auto-worktree-suite.mjs); `tests/**` виключено з npm-tarball; `jscpd` (спавниться як `bunx jscpd`) додано в knip ignoreDependencies
+
+## [1.26.0] - 2026-07-19
+
+### Changed
+
+- Фаза 5a spec lang-plugins-extraction: ядро — двигун без мовної специфіки. npm/bun-гілка taze виїхала в плагін `@7n/rules-lang-js` (EcosystemProvider; бекап воркспейсів, `bunx taze -w -r latest` + `bun install`, collectTazeDiff, SKILL-фрагмент); semver-примітиви (parseVersion/isBreaking) тепер визначені в `@7n/rules/plugin-api` (було — реекспорт із diff.mjs). Оркестратор — чистий цикл провайдерів (без вбудованих гілок), звіт — рівноправні секції екосистем; CLI `n-rules taze diff` резолвиться через handler lang-js. Автодетект — кореневий package.json → lang-js
+
 ## [1.25.1] - 2026-07-19
 
 ### Fixed

package/bin/n-rules.js

@@ -1883,7 +1883,22 @@ try {
         // n-rules taze diff — read-only semver-diff package.json ↔ package.json.taze-bak
         // (root + воркспейси) для скілу n-taze: скрипт класифікує major-оновлення,
         // агент отримує готовий список замість ручного порівняння бекапів.
-        const { runTazeCli } = await import('../skills/taze/js/diff.mjs')
+        // Живе у плагіні @7n/rules-lang-js (фаза 5a spec lang-plugins-extraction) —
+        // резолвимо його taze-handler і беремо named-експорт runTazeCli.
+        const { getHandlers } = await import('../scripts/lib/resolve-plugins.mjs')
+        const { readNRulesConfigLite } = await import('../scripts/lib/read-n-rules-config-lite.mjs')
+        const config = await readNRulesConfigLite(cwd())
+        const handler = getHandlers(cwd(), config, 'taze').find(h => h.pluginName === '@7n/rules-lang-js')
+        if (!handler) {
+          console.error(
+            '❌ taze diff потребує плагін @7n/rules-lang-js (npm/bun-гілка) — запусти npx @7n/rules для авто-встановлення'
+          )
+          process.exitCode = 1
+          break
+        }
+        const { pathToFileURL } = await import('node:url')
+        // eslint-disable-next-line no-unsanitized/method
+        const { runTazeCli } = await import(pathToFileURL(handler.modulePath).href)
         process.exitCode = await runTazeCli(args)
 
         break

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.25.1",
+  "version": "1.27.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",
@@ -43,6 +43,7 @@
     "!**/*.test.mjs",
     "!**/*_test.rego",
     "!**/test-helpers.mjs",
+    "!**/tests/**",
     "!**/fixtures/**",
     "!**/__fixtures__/**"
   ],

package/rules/doc-files/docgen-crc/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-crc/main.mjs
 docgen:
-  crc: c10183ef
+  crc: 8976f6f8
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99

package/rules/doc-files/docgen-crc/main.mjs

@@ -67,24 +67,17 @@ export function parseDocFrontmatter(md) {
 /** Максимум кодів issues у frontmatter — це маркер, а не повний лог. */
 const MAX_ISSUE_CODES = 8
 
-/** OKF type для вбудованих розширень; мовні (`.rs`, `.py`) декларують lang-плагіни. */
-const EXT_TYPES = {
-  '.js': 'JS Module',
-  '.mjs': 'JS Module',
-  '.cjs': 'JS Module',
-  '.ts': 'TS Module',
-  '.vue': 'Vue Component'
-}
-
 /**
- * OKF `type` для файлу-джерела за розширенням (вбудовані + декларації
- * активних lang-плагінів).
+ * OKF `type` для файлу-джерела за розширенням — лише з декларацій активних
+ * lang-плагінів (`contributes.docFiles.extensions`: js/mjs/ts/vue — lang-js,
+ * `.rs`/`.py` — lang-rust/lang-python); вбудованих типів у ядрі немає
+ * (фаза 5b spec lang-plugins-extraction). Невідоме розширення → 'Source File'.
  * @param {string} sourcePath відносний шлях джерела
  * @returns {string} тип концепту
  */
 function typeForSource(sourcePath) {
   const ext = extname(sourcePath).toLowerCase()
-  return EXT_TYPES[ext] ?? pluginDocFilesExtensions(process.cwd())[ext] ?? 'Source File'
+  return pluginDocFilesExtensions(process.cwd())[ext] ?? 'Source File'
 }
 
 /**

package/rules/doc-files/docgen-gen/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: 358294dc
+  crc: ed99ac58
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

package/rules/doc-files/docgen-gen/main.mjs

@@ -8,7 +8,6 @@ import { startChain } from '@7n/llm-lib/chain'
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { docPathForSource } from '../docgen-scan/main.mjs'
 import { loadDocFilesExtractors } from '../docgen-scan/lang-extensions.mjs'
-import { extractFacts } from '../docgen-extract/main.mjs'
 import { extractAnchors, anchorTokens } from '../docgen-extract-anchors/main.mjs'
 import { QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
 import { JUDGE_ENABLED, JUDGE_MODEL, detectRefusalFiller, judgeDoc, judgeFailsDoc } from '../docgen-judge/main.mjs'
@@ -507,11 +506,20 @@ export async function generateDoc(
       `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
     )
   }
-  // Мовний екстрактор з lang-плагіна (напр. `.rs` у @7n/rules-lang-rust) має
-  // пріоритет; вбудований extractFacts покриває JS-екосистему, решта — whole-file.
+  // Факт-лист — лише від мовного екстрактора lang-плагіна (js/mjs/ts —
+  // lang-js, `.rs` — lang-rust); без екстрактора для розширення — whole-file
+  // шлях через `unsupported` (у ядрі вбудованих екстракторів немає, фаза 5b).
   const langExtractors = await loadDocFilesExtractors(process.cwd())
   const ext = `.${file.split('.').pop()}`.toLowerCase()
-  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? extractFacts(src, file)
+  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? {
+    relPath: file,
+    lang: ext.slice(1),
+    unsupported: true,
+    header: '',
+    exports: [],
+    imports: {},
+    markers: {}
+  }
   const t0 = Date.now()
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })

package/rules/doc-files/docgen-scan/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-scan/main.mjs
 docgen:
-  crc: 66000db2
+  crc: 8729f94f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99
@@ -15,7 +15,7 @@ docgen:
 
 ## Поведінка
 
-isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів.
+isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів; перелік кодових розширень береться ВИКЛЮЧНО з декларацій активних lang-плагінів (`contributes.docFiles.extensions`: js/mjs/ts/vue — lang-js, `.rs`/`.py` — lang-rust/lang-python), у ядрі вбудованих розширень немає (фаза 5b) — без активного lang-плагіна скан не бачить жодного джерела.
 docPathForSource обчислює очікуваний шлях до markdown-документа для заданого кодового джерельного шляху, розміщуючи його у теці `docs` поруч із джерелом.
 isDocCandidate визначає, чи повинен файл підлягати документуванню, перевіряючи його тип, статус тесту, статус ігнорування та чи не є він частиною системних документації.
 describeFile описує кодовий файл, надаючи шлях джерела та шлях до відповідного документа, а також статус його застарілості за CRC. Якщо док-файл існує, але без `docgen:`-CRC у frontmatter (рукописна дока), файл позначається `foreign: true` і НЕ вважається застарілим — людський зміст рахується чинною документацією і мовчки не перезаписується (перезапис лише explicit `--overwrite` у batch-CLI).

package/rules/doc-files/docgen-scan/main.mjs

@@ -7,13 +7,6 @@ import { isDocgenIgnored } from '../docgen-ignore/main.mjs'
 import { parseDocFrontmatter, readDocCrc, staleness } from '../docgen-crc/main.mjs'
 import { pluginDocFilesExtensions } from './lang-extensions.mjs'
 
-/**
- * Вбудовані кодові розширення, для яких генеруємо документацію. Мовні
- * розширення поза JS-екосистемою (`.rs`, `.py`) декларують lang-плагіни
- * (`n-rules.contributes.docFiles.extensions`) — див. lang-extensions.mjs.
- */
-const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue'])
-
 /** `*.test.*`, `*.spec.*`, `*.stories.*` — тести й Storybook CSF-файли, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec|stories)\.[^.]+$/u
 
@@ -29,18 +22,18 @@ function isSystemWideDocsRoot(root) {
 }
 
 /**
- * Чи є файл кодовим джерелом для документування. З `root` — враховує і
- * розширення активних lang-плагінів; без нього — лише вбудовані JS-екосистемні.
+ * Чи є файл кодовим джерелом для документування. Розширення декларують ЛИШЕ
+ * активні lang-плагіни (`n-rules.contributes.docFiles.extensions` — js/mjs/ts/vue
+ * дає `@7n/rules-lang-js`, .rs/.py — lang-rust/lang-python); у ядрі вбудованих
+ * розширень немає (фаза 5b spec lang-plugins-extraction).
  * @param {string} fileName базове ім'я файлу
- * @param {string} [root] корінь репозиторію (для плагінних розширень)
+ * @param {string} root корінь репозиторію (джерело плагінних розширень)
  * @returns {boolean} true — документуємо; false — пропускаємо
  */
 export function isSourceFile(fileName, root) {
   if (fileName.endsWith('.d.ts')) return false
   if (TEST_FILE_RE.test(fileName)) return false
-  const ext = extname(fileName)
-  if (SOURCE_EXTENSIONS.has(ext)) return true
-  return root !== undefined && ext in pluginDocFilesExtensions(root)
+  return extname(fileName) in pluginDocFilesExtensions(root)
 }
 
 /**

package/rules/js/eslint/concern.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "skipLocalTier": true,
   "lint": {
     "scope": "per-file",
     "glob": ["**/*.{js,mjs,cjs,jsx,ts,tsx,vue}"]

package/schemas/concern.json

@@ -19,6 +19,10 @@
       ],
       "description": "Маршрутизація fix-движка. Усі мітки виконують детерміновану фазу T0; різниця — що після неї. `code` (дефолт, поле можна опускати) — джерельні порушення, які LLM може осмислено переписати → повна pi-agent-ladder (local→cloud) до чистого re-detect. `config` — canon/settings/tooling конфіг з єдиною правильною формою (jscpd/oxfmtrc/tooling/package_json/*_yml): фікс детермінований (T0/regen з канону), LLM лише вгадав би невалідне → після T0 fail-fast без ladder. `structural` — дублікати/розташування/структура (jscpd_duplicates/test-location/package-structure): авто-правка ризикована й потребує людського розсуду → після T0 fail-fast без ladder. config vs structural різняться мотивом пропуску (детермінований канон vs надто ризиковано) — для телеметрії й майбутнього routing."
     },
+    "skipLocalTier": {
+      "type": "boolean",
+      "description": "Дефолт `false` (поле можна опускати). `true` пропускає local-min/local-min-retry rung-и LLM-ladder-а для цього concern-а — перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier (слабка локальна модель, короткий бюджет) емпірично майже завжди лише витрачає час rung-а без результату, перш ніж ladder однаково ескалює далі."
+    },
     "check": {
       "type": "boolean",
       "const": true,

package/scripts/lib/concern-meta.mjs

@@ -34,6 +34,10 @@ import { join } from 'node:path'
  * @property {PolicySurface|undefined} policy policy-поверхня concern-а (rego/template) або undefined.
  * @property {LintSurface|undefined} lint lint-поверхня concern-а або undefined.
  * @property {Fixability} fixability маршрутизація fix-движка (дефолт `code`): `config`/`structural` пропускають LLM-ladder.
+ * @property {boolean} skipLocalTier дефолт `false`: `true` пропускає local-min/local-min-retry rung-и
+ *   ladder-а — ladder одразу стартує з cloud-min. Для concern-ів, де local-tier емпірично не встигає
+ *   дати результат у межах свого бюджету (напр. js/eslint — 0/12 успіхів у реальному прогоні, лише
+ *   витрачений час).
  */
 
 /**
@@ -119,7 +123,16 @@ export async function readConcernMeta(concernDir, name) {
       ? raw.requires.capability
       : undefined
 
-  return { name, dir: concernDir, check, policy, lint, requiresCapability, fixability: parseFixability(raw.fixability) }
+  return {
+    name,
+    dir: concernDir,
+    check,
+    policy,
+    lint,
+    requiresCapability,
+    fixability: parseFixability(raw.fixability),
+    skipLocalTier: raw.skipLocalTier === true
+  }
 }
 
 /**

package/scripts/lib/docs/concern-meta.md

@@ -3,12 +3,8 @@ type: JS Module
 title: concern-meta.mjs
 resource: npm/scripts/lib/concern-meta.mjs
 docgen:
-  crc: 1675429b
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
-  score: 100
-  issues: judge:inaccurate:0.97
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: ccc325b1
+  model: manual
 ---
 
 ## Огляд
@@ -21,6 +17,7 @@ docgen:
 readConcernMeta зчитує і перевіряє файл concern.json у вказаній директорії concern-а, повертаючи метадані або null, якщо файл відсутній чи не валідний.
 listConcerns сканує директорію правил і повертає список усіх знайдених concern-ів у алфавітному порядку, ігноруючи каталоги без concern.json.
 Нормалізований meta несе `fixability` (`code`|`config`|`structural`); невідоме/відсутнє значення зводиться до `code` — дефолт, за яким concern лишається eligible для LLM-fix-ladder.
+Нормалізований meta несе також `skipLocalTier` (boolean, дефолт `false`): `true` — concern пропускає local-min/local-min-retry rung-и LLM-ladder-а, перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier емпірично майже завжди лише витрачає бюджет rung-а без результату (напр. `js/eslint`).
 
 ## Публічний API
 

package/scripts/lib/docs/plugin-api.md

@@ -3,9 +3,8 @@ type: JS Module
 title: plugin-api.mjs
 resource: npm/scripts/lib/plugin-api.mjs
 docgen:
-  crc: dc4f4a12
+  crc: c614a880
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min-retry
   score: 100
   issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini

package/scripts/lib/docs/resolve-plugins.md

@@ -3,7 +3,7 @@ type: JS Module
 title: resolve-plugins.mjs
 resource: npm/scripts/lib/resolve-plugins.mjs
 docgen:
-  crc: 0d197e39
+  crc: fb58860d
 ---
 
 Резолв плагінів @7n/rules: визначає, які пакети-плагіни активні у проєкті, де їхні `rules/`-каталоги, які capabilities вони надають і які handlers надають.

package/scripts/lib/lint-surface/docs/ladder.md

@@ -3,10 +3,8 @@ type: JS Module
 title: ladder.mjs
 resource: npm/scripts/lib/lint-surface/ladder.mjs
 docgen:
-  crc: a5e45f08
-  model: openai-codex/gpt-5.5
-  score: 100
-  issues: judge:inaccurate:0.97
+  crc: f02de1a2
+  model: manual
 ---
 
 ## Огляд
@@ -17,7 +15,7 @@ docgen:
 
 - `DEFAULT_MAX_AVG` задає типовий ліміт звернень до середнього cloud-рівня за один прогін, щоб ескалація не витрачала надмірно дорогий ресурс.
 - `buildLadder` формує послідовність рівнів виправлення від локального мінімального до cloud-avg і відкидає недоступні рівні без моделі.
-- Кожен rung несе `timeoutMs` — per-tier таймаут виклику (ADR 260620-0556): локальні рівні 45s, хмарні 120s; override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` (мс на ОДИН rung відповідного класу; невалідне значення → дефолт). Runner прокидає його worker-у через `FixContext`, щоб зависла LLM-сесія переривалась (runner додатково тримає backstop ×1.25), а ladder рухався далі. Це робочий важіль для повільної локальної моделі чи великої черги batch-концерну (doc-files ріже беклог під цей ліміт м'яким дедлайном).
+- Кожен rung несе `timeoutMs` — per-tier таймаут виклику (ADR 260620-0556): локальні рівні 45s, cloud-min 120s, cloud-avg 180s (окремий, більший дефолт — реальний прогін 2026-07-18 показав, що cloud-avg регулярно доводить concern майже до чистого re-detect, але спільний з cloud-min бюджет не лишав часу на verify, а наступного rung-а для повторної спроби нема); override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` / `N_CLOUD_AVG_FIX_TIMEOUT_MS` (мс на ОДИН rung відповідного класу; невалідне значення → дефолт). Runner прокидає його worker-у через `FixContext`, щоб зависла LLM-сесія переривалась (runner додатково тримає backstop ×1.25), а ladder рухався далі. Це робочий важіль для повільної локальної моделі чи великої черги batch-концерну (doc-files ріже беклог під цей ліміт м'яким дедлайном).
 - `classifyFixError` визначає характер помилки виправлення: системна причина, транспортний збій або якісна невдача агента.
 - `decideAfterFailure` вирішує, чи продовжувати ескалацію після невдалого рівня, чи пропустити локальну модель, чи зупинити процес.
 

package/scripts/lib/lint-surface/docs/run-fix.md

@@ -3,8 +3,8 @@ type: JS Module
 title: run-fix.mjs
 resource: npm/scripts/lib/lint-surface/run-fix.mjs
 docgen:
-  crc: c4235855
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 45965f7d
+  model: manual
 ---
 
 ## Огляд
@@ -23,6 +23,7 @@ Durable-write-и (issue nitra/cursor#16): worker отримує у `FixContext`
 MT-tail (Фаза B, спека 2026-07-11): коли лишився невиправлений хвіст (worst=1), `renderRemaining` повертає зібрані порушення, і вони матеріалізуються у вузли MT-графа через `materializeTail` (mt-tail.mjs). Єдиний гейт — onboarded-репо (наявність `.mt.json`); fail-open: MT недоступний або будь-яка помилка → лог, lint не падає.
 Distillation-телеметрія (Фаза C, §13 pi-migration): успішний agentic-рунг (canonical clean, без veto, з реальними правками у worker telemetry) пише запис `oldText→newText` у глобальний стор (`recordFixTelemetry`, `~/.n-rules/telemetry/<rule>/open/`) — корпус для маховика дистиляції T0. Best-effort; T0/ручні фікси не пишуться.
 Rollback на провалі re-detect-а: якщо canonical re-detect усередині rung-а сам кидає виняток (worker/LLM лишив файл синтаксично невалідним — детектор/conftest не може його розпарсити), `runRung` спершу відкочує `snapshot` до S1, і лише потім перекидає виняток далі — без цього зіпсований проміжний стан worker-а лишався б на диску назавжди (виняток абортує весь прогін до звичайного rollback-коду).
+skipLocalTier (concern-meta.mjs): `selectLadder` перед циклом ladder-а фільтрує з нього local-min/local-min-retry rung-и, якщо `item.entry.concern.skipLocalTier === true` — перша спроба одразу йде на cloud-min. Для concern-ів, де local-tier емпірично майже завжди лише витрачає бюджет rung-а без результату (виявлено на реальному прогоні 2026-07-18: 0/12 успіхів local-tier для `js/eslint`).
 
 ## Публічний API
 

package/scripts/lib/lint-surface/ladder.mjs

@@ -9,16 +9,25 @@ import { env } from 'node:process'
 // об'єктивно не закінчить важкий промпт за хвилини (curl 28), хмарний SSE без
 // таймауту здатен висіти годинами на ESTABLISHED TCP — драбина має рухатись далі.
 //
-// Override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS`:
-// мілісекунди на ОДИН rung відповідного класу (local-min/local-min-retry та
-// cloud-min/cloud-avg). Значення потрапляє worker-у як `ctx.timeoutMs` (внутрішній
-// abort LLM-виклику; batch-worker-и, як doc-files, ріжуть під нього беклог м'яким
-// дедлайном), а runner додатково тримає backstop ×1.25 навколо всього worker-виклику.
-// Робочий важіль для повільної локальної моделі чи великої черги batch-концерну:
-// підняти локальний таймаут понад вартість одного файлу. Невалідне значення
-// (NaN/0/порожньо) → дефолт.
+// Override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` /
+// `N_CLOUD_AVG_FIX_TIMEOUT_MS`: мілісекунди на ОДИН rung відповідного класу
+// (local-min/local-min-retry, cloud-min, cloud-avg). Значення потрапляє worker-у як
+// `ctx.timeoutMs` (внутрішній abort LLM-виклику; batch-worker-и, як doc-files, ріжуть
+// під нього беклог м'яким дедлайном), а runner додатково тримає backstop ×1.25 навколо
+// всього worker-виклику. Робочий важіль для повільної локальної моделі чи великої черги
+// batch-концерну: підняти локальний таймаут понад вартість одного файлу. Невалідне
+// значення (NaN/0/порожньо) → дефолт.
+//
+// cloud-avg має ОКРЕМИЙ (більший за cloud-min) дефолт: реальний прогін
+// (2026-07-18, /ai run/yoga2, chainId 6f6b4fdca71aa0c5) показав, що cloud-avg
+// регулярно доводить concern до 1 залишкового порушення в межах спільного з
+// cloud-min бюджету, але verify (canonical re-detect) не встигає підтвердитись —
+// і весь прогрес відкочується, бо після cloud-avg немає наступного rung-а для
+// повторної спроби. cloud-avg — останній шанс ladder-а (і під DEFAULT_MAX_AVG-кепом),
+// тож дорожчий за нього бюджет виправдано менш економний, ніж cloud-min.
 const LOCAL_TIMEOUT_MS = Number(env.N_LOCAL_FIX_TIMEOUT_MS) || 45_000
 const CLOUD_TIMEOUT_MS = Number(env.N_CLOUD_FIX_TIMEOUT_MS) || 120_000
+const CLOUD_AVG_TIMEOUT_MS = Number(env.N_CLOUD_AVG_FIX_TIMEOUT_MS) || 180_000
 
 /** Дефолтний кеп на виклики cloud-avg за прогін (щоб ladder на N concern-ів не спалив avg). */
 export const DEFAULT_MAX_AVG = 3
@@ -59,7 +68,7 @@ export function buildLadder({ localMin, cloudMin, cloudAvg }) {
       timeoutMs: LOCAL_TIMEOUT_MS
     },
     { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false, timeoutMs: CLOUD_TIMEOUT_MS },
-    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_TIMEOUT_MS }
+    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true, timeoutMs: CLOUD_AVG_TIMEOUT_MS }
   ].filter(r => r.model)
 }
 

package/scripts/lib/lint-surface/run-fix.mjs

@@ -440,6 +440,18 @@ function noteT0Phase(t0, chainExtra, touchedAbs) {
   }
 }
 
+/**
+ * Ladder concern-а: повний, або без local-tier rung-ів (`concern.skipLocalTier`) —
+ * concern-и, де local-min/local-min-retry емпірично не встигають дати результат
+ * у межах свого бюджету (concern-meta.mjs).
+ * @param {Rung[]} ladder Повний ladder pipeline-у.
+ * @param {import('../concern-meta.mjs').ConcernMeta} concern Concern-meta елемента плану.
+ * @returns {Rung[]} Ladder, застосовний до цього concern-а.
+ */
+function selectLadder(ladder, concern) {
+  return concern.skipLocalTier ? ladder.filter(rung => !rung.local) : ladder
+}
+
 /**
  * Тіло fix-pipeline одного concern-а (T0 → S1 → ladder); chain/chainExtra — акумулятори
  * телеметрії ланцюжка (володіє ними fixConcern-обгортка).
@@ -481,7 +493,8 @@ async function fixConcernCore(item, initialViolations, deps, chain, chainExtra,
 
   // ── Worker ladder ── concern-specific fix-worker.mjs, інакше дефолтний pi-agent worker.
   const worker = await resolveWorker(concernDir, deps.workerOverride)
-  if (!worker || ladder.length === 0) {
+  const effectiveLadder = selectLadder(ladder, item.entry.concern)
+  if (!worker || effectiveLadder.length === 0) {
     chainExtra.stop = 'no-worker'
     return false
   }
@@ -492,7 +505,7 @@ async function fixConcernCore(item, initialViolations, deps, chain, chainExtra,
   let violations = initialViolations
   const skipModels = new Set()
 
-  for (const rung of ladder) {
+  for (const rung of effectiveLadder) {
     if (skipModels.has(rung.model)) continue
     if (rung.isAvg && deps.avgRemaining() <= 0) {
       log(`  ⏭️  ${ruleId}/${concernName}: ${rung.tier} пропущено (avg-кеп вичерпано)\n`)

package/scripts/lib/plugin-api.mjs

@@ -7,11 +7,40 @@
  * модуль-обробник експортує обʼєкт провайдера як `default`. Наступні порти
  * (doc-files, lint) додаються окремими фазами — не проєктуються наперед.
  *
- * Semver-утиліти ядра реекспортуються звідси, щоб плагіни класифікували
- * major/minor за тим самим правилом caret-семантики, що й ядро, без
- * дублювання коду і без імпорту внутрішніх шляхів `@7n/rules`.
+ * Semver-утиліти (caret-класифікація major/minor) живуть саме тут — єдине
+ * джерело правила для всіх мовних плагінів, без імпорту внутрішніх шляхів
+ * `@7n/rules` і без циклу plugin-api ↔ плагін.
  */
-export { isBreaking, parseVersion } from '../../skills/taze/js/diff.mjs'
+// Заякорено на початок (після можливих range-операторів `^~>=<`, пробілів, `v`),
+// щоб НЕ ловити версію всередині protocol-specifier-ів (`workspace:1.0.0`, `npm:x@1.2.3`).
+const SEMVER_RE = /^[\s~^>=<v]*(\d+)\.(\d+)\.(\d+)/
+
+/**
+ * Парсить semver-ядро зі specifier-а (ігнорує range-префікси `^`/`~`/`>=` тощо).
+ * @param {string} spec версійний specifier із package.json
+ * @returns {{major:number, minor:number, patch:number}|null} ядро або null для не-semver (`workspace:*`, git-url, `*`)
+ */
+export function parseVersion(spec) {
+  if (typeof spec !== 'string') return null
+  const m = SEMVER_RE.exec(spec)
+  if (!m) return null
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) }
+}
+
+/**
+ * Чи є перехід `from → to` breaking за caret-семантикою (змінилась найлівіша
+ * ненульова компонента).
+ * @param {{major:number,minor:number,patch:number}} from стара версія
+ * @param {{major:number,minor:number,patch:number}} to нова версія
+ * @returns {boolean} true — major/breaking
+ */
+export function isBreaking(from, to) {
+  if (from.major !== to.major) return true
+  if (from.major > 0) return false
+  if (from.minor !== to.minor) return true
+  if (from.minor > 0) return false
+  return from.patch !== to.patch
+}
 
 /** Версія контракту plugin-api: плагін декларує `requiresPluginApi`, несумісність → skip, не креш. */
 export const PLUGIN_API_VERSION = 1

package/scripts/lib/resolve-plugins.mjs

@@ -31,11 +31,12 @@ export const KNOWN_CI_PLUGINS = Object.freeze({
 /**
  * Відомі мовні плагіни: файловий сигнал екосистеми → npm-пакет. `maxDepth` —
  * до якої глибини шукати сигнал: python — лише корінь (uv-провайдер v1
- * обробляє тільки кореневий pyproject.toml); rust — до 3 рівнів, бо в
+ * обробляє тільки кореневий pyproject.toml; js — кореневий package.json); rust — до 3 рівнів, бо в
  * монорепо Cargo.toml часто вкладений (Tauri `app/src-tauri/Cargo.toml`),
  * а провайдер обробляє всі знайдені маніфести.
  */
 export const KNOWN_LANG_PLUGINS = Object.freeze({
+  js: { signal: 'package.json', pkg: '@7n/rules-lang-js', maxDepth: 0 },
   python: { signal: 'pyproject.toml', pkg: '@7n/rules-lang-python', maxDepth: 0 },
   rust: { signal: 'Cargo.toml', pkg: '@7n/rules-lang-rust', maxDepth: 3 }
 })

package/scripts/utils/docs/test-helpers.md

@@ -3,7 +3,7 @@ type: JS Module
 title: test-helpers.mjs
 resource: npm/scripts/utils/test-helpers.mjs
 docgen:
-  crc: 9af8ee18
+  crc: a01017b0
 ---
 
 ## Огляд
@@ -18,6 +18,7 @@ docgen:
 - `withBinStubInPath(bin, fn)` — створює тимчасовий каталог зі стабом `<bin>` (`<bin>.exe` на Windows), що завершується з кодом 0, додає каталог на початок `PATH` на час `fn`, потім відновлює `PATH` і прибирає стаб. Реальний бінарник не запускається: і машини без інструмента, і повільні мережево-залежні інструменти (наприклад, `kubescape`, який на старті тягне артефакти з хмарних API десятки секунд) отримують детермінований швидкий прогін.
 - `withShellcheckStubInPath(fn)` — спеціалізація `withBinStubInPath` для `shellcheck` (перевірки `check ga` на машинах без реального shellcheck).
 - `withBinRemovedFromPath(bin, fn)` — виконує `fn` із `PATH`, з якого прибрані всі каталоги з виконуваним `<bin>`; решта `PATH` (git, bun) лишається. На час `fn` виставляє `N_CURSOR_NO_AUTO_INSTALL=1`, щоб `ensureTool` не запускав реальний brew/scoop/curl-install. Для негативних тестів «fail, коли інструмента нема».
+- `installFakeLangJsPlugin(dir)` — кладе у tmp-репо фейковий `@7n/rules-lang-js` (маніфест із doc-files-розширеннями js/mjs/ts/vue у `node_modules`) і активує його через `.n-rules.json`. Після фази 5b ядро не має вбудованих кодових розширень — тестам doc-files без цього хелпера скан не бачить жодного джерела.
 
 ## Гарантії поведінки
 

package/skills/doc-files/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: doc-files
 description: >-
-  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue вбудовано; rs/py — через lang-плагіни) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (розширення декларують lang-плагіни: js/mjs/ts/vue — lang-js, rs/py — lang-rust/lang-python) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
 version: '1.0'
 ---