@7n/rules 1.48.2 → 1.49.0

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

@@ -3,39 +3,50 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: c02d3a1f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 80c789c7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 10
+  issues: no-overview,short-behavior,internal-name:isApiGap,internal-name:renderApiLine,internal-name:oneShotDoc,internal-name:finishUnsupported,anchor-miss:(abie.mdc),best-of-2:retry-lost
 ---
 
-## Огляд
-
-Огляд
-Створює технічну документацію шляхом аналізу вихідного коду, генерації тексту, оцінки його якості та управління позиціонуванням захищеного блоку «Призначення» у фінальному документі. (abie.mdc)
-
-Поведінка
-splitProtected відокремлює захищений блок «Призначення» від основного вмісту документа, надаючи його тіло та текст без цього блоку.
-insertProtected поміщає захищений блок «Призначення» одразу після основного заголовка документа, якщо надано його тіло.
-scoreDoc оцінює згенерований документ за заданими критеріями, визначаючи його якість та реєструючи проблеми.
-DEFAULT_LOCAL_MODEL встановлює модель, яку використовувати для генерації документа, якщо не вказано іншу.
-generateDoc створює повний технічний документ з вихідного файлу, включаючи вихідну оцінку якості.
-
-## Поведінка
-
-splitProtected відокремлює захищений блок «Призначення» від основного вмісту документа, повертаючи його тіло та текст без цього блоку.
-insertProtected розміщує захищений блок «Призначення» одразу після основного заголовка документа, якщо його тіло було надано.
-scoreDoc оцінює згенерований документ за набором детермінованих правил (generic-огляд, коротка поведінка, галюцинації про кеш, витік службових імен, анкор-покриття, суржик) і реєструє коди проблем. Правило R8 — refusal/чат-філер («Я готовий писати…», «Надайте мені код…», через пре-гейт docgen-judge): форсує degraded незалежно від структурної оцінки, тож LLM-суддя на такому змісті не викликається; захищене людське «Призначення» з перевірки виключене.
-DEFAULT_LOCAL_MODEL визначає модель за замовчуванням для генерації документа, якщо не вказано інше.
-generateDoc створює повний технічний документ з вихідного файлу, включаючи детерміновану оцінку якості; для непідтримуваних структур (one-shot шлях) оцінка не застосовується, але refusal-пре-гейт діє і там — філер отримує score 0 і позначку degraded, щоб доретрай батчу підібрав файл.
-generateDoc приймає опційний `deadlineAt` (м'який дедлайн fix-pipeline, epoch ms): кожен LLM-виклик ріже свій таймаут під залишок бюджету (`capTimeoutToDeadline`), а вичерпаний бюджет обриває генерацію помилкою зі словом «timeout» ще до старту виклику — батч класифікує її як transient, і генерація ніколи не переживає бюджет рунга (без батчу-зомбі поверх наступного rung-а).
-
 ## Публічний API
 
-splitProtected — витягує тіло захищеної секції «Призначення» та повертає документ без неї.
-insertProtected — повертає захищений блок у фіксовану позицію одразу після заголовка документа.
-scoreDoc — детермінований скоринг документа (0 токенів) проти факт-листа: оцінка 0–100 і коди проблем.
-DEFAULT_LOCAL_MODEL — модель генерації за замовчуванням (env-конфігурована; без неї preflight фейлить гучно).
-generateDoc — головний вхід: джерело → md-дока з оцінкою якості, best-of-2 повтором і опційним семантичним суддею; опційний `deadlineAt` обмежує генерацію бюджетом рунга fix-pipeline.
-capTimeoutToDeadline — ріже базовий per-call таймаут під залишок до дедлайну (без дедлайну — базовий ліміт; після дедлайну — 0).
+- capTimeoutToDeadline — Ріже базовий per-call таймаут під залишок бюджету до дедлайну.
+Без дедлайну — базовий ліміт; після дедлайну — 0 (виклик не має стартувати).
+- stripLeadingPreamble — R9: зрізає провідні чат-преамбули й дубль назви секції з початку тексту.
+Ітерується, поки перший непорожній рядок лишається мета-нарацією — модель
+інколи ставить дві поспіль («Як технічний письменник…» + «Ось оновлений…»).
+- splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## `
+(H2); `###`+ усередині не обривають блок.
+- insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція).
+- scoreDoc — Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
+- buildApiSection — Stage 1/3 (гібрид doc-files, ADR 260719-2155): «Публічний API» — покриті
+JSDoc-описом експорти рендеряться дослівно (`renderApiLine`, 0 токенів, 0
+галюцинацій), LLM викликається лише на прогалини (`isApiGap`). Якщо прогалин
+немає — секція збирається БЕЗ жодного LLM-виклику. Єдиний непокритий
+експорт (як і раніше) лишається описаним лише в Поведінці — окремого виклику
+на секцію з одного рядка не варте.
+- DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') (→ N_LOCAL_MIN_MODEL).
+Без хардкод-fallback: модель налаштовує кожен локально (`N_LOCAL_MIN_MODEL`); якщо
+нічого не задано — порожньо, і preflight оркестратора фейлить гучно (а не шле
+запит до неіснуючої моделі).
+- generateDoc — Головний API: файл → md-дока з det-оцінкою.
+
+Local-only (ADR 260610-2228): жодних cloud-ескалацій і pre-route — будь-який
+файл генерується локальною моделлю. Якщо det-score нижче порогу, один retry
+з вищою температурою (best-of-2); якщо й він не допоміг — результат
+позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
+- prepareBatchItem — T8 (2b-batch, рішення Р): підготовка ОДНОГО item-у для `submitBatch` — та сама
+pre-send guard і той самий факт-лист/one-shot messages, що й `oneShotDoc`/
+`generateDoc`, але БЕЗ виклику LLM (виклик робить batch-шар одним `submit` на
+всі файли разом). Кидає ту саму помилку pre-send guard, що й `generateDoc`
+(класифікується `permanent` у batch-оркестраторі — skip, не помилка прогону).
+- finishBatchItem — T8 (2b-batch): постобробка ОДНОГО результату `submitBatch` — той самий фініш,
+що й `oneShotDoc`/`finishUnsupported`/det-скорер, тільки без LLM-виклику
+(текст уже отримано з batch-у). Judge-гейт (Stage 3) у batch-шляху НЕ
+викликається (мінімальний обсяг T8 — генерація; judge лишається опційним
+розширенням послідовного шляху).
 
 ## Гарантії поведінки
 

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

@@ -602,6 +602,39 @@ const DEFAULT_CONTEXT_TOKENS = 131072
 function srcTokenBudget() {
   return Math.floor((Number(env.N_CURSOR_DOCGEN_CTX) || DEFAULT_CONTEXT_TOKENS) * 0.5)
 }
+
+/**
+ * Спільний pre-LLM preflight для `generateDoc` і `prepareBatchItem` (T8 2b-batch):
+ * читає джерело, ріже гігантів до LLM-виклику (pre-send guard — «Prompt too long»
+ * без жодного виклику) і резолвить факт-лист через мовний екстрактор lang-плагіна
+ * (js/mjs/ts — lang-js, `.rs` — lang-rust; whole-file `unsupported`-fallback, якщо
+ * екстрактора для розширення нема).
+ * @param {string} file абсолютний шлях джерела
+ * @returns {Promise<{ src: string, estTokens: number, ext: string, langExtractors: Map<string, object>, facts: object }>} усе потрібне обом callers перед LLM-викликом
+ */
+async function loadSrcAndFacts(file) {
+  const src = readFileSync(file, 'utf8')
+  const estTokens = Math.round(Buffer.byteLength(src, 'utf8') / 4)
+  const budget = srcTokenBudget()
+  if (estTokens > budget) {
+    throw new Error(
+      `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
+    )
+  }
+  const langExtractors = await loadDocFilesExtractors(process.cwd())
+  const ext = `.${file.split('.').pop()}`.toLowerCase()
+  const facts = langExtractors.get(ext)?.extractFacts?.(src, file) ?? {
+    relPath: file,
+    lang: ext.slice(1),
+    unsupported: true,
+    header: '',
+    exports: [],
+    imports: {},
+    markers: {}
+  }
+  return { src, estTokens, ext, langExtractors, facts }
+}
+
 /**
  * Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') (→ N_LOCAL_MIN_MODEL).
  * Без хардкод-fallback: модель налаштовує кожен локально (`N_LOCAL_MIN_MODEL`); якщо
@@ -654,32 +687,8 @@ export async function generateDoc(
     deadlineAt = null
   } = {}
 ) {
-  const src = readFileSync(file, 'utf8')
-  // Pre-send guard: весь src вшивається у промпт як є (екстракт фактів його НЕ
-  // замінює). Для гігантів (vendored/генерат) це переповнює контекст → інстант-skip
-  // без LLM-виклику. Маркер «Prompt too long» → classifyOmlxError → permanent → skip.
   // Guard ДО створення ланцюжка: skip без LLM — не задача.
-  const estTokens = Math.round(Buffer.byteLength(src, 'utf8') / 4)
-  const budget = srcTokenBudget()
-  if (estTokens > budget) {
-    throw new Error(
-      `docgen pre-send guard: джерело ~${estTokens} токенів > бюджет ${budget} (0.5× контексту) — Prompt too long, skip`
-    )
-  }
-  // Факт-лист — лише від мовного екстрактора 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) ?? {
-    relPath: file,
-    lang: ext.slice(1),
-    unsupported: true,
-    header: '',
-    exports: [],
-    imports: {},
-    markers: {}
-  }
+  const { src, estTokens, ext, langExtractors, facts } = await loadSrcAndFacts(file)
   const t0 = Date.now()
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })
@@ -770,6 +779,51 @@ export async function generateDoc(
   }
 }
 
+/**
+ * T8 (2b-batch, рішення Р): підготовка ОДНОГО item-у для `submitBatch` — та сама
+ * pre-send guard і той самий факт-лист/one-shot messages, що й `oneShotDoc`/
+ * `generateDoc`, але БЕЗ виклику LLM (виклик робить batch-шар одним `submit` на
+ * всі файли разом). Кидає ту саму помилку pre-send guard, що й `generateDoc`
+ * (класифікується `permanent` у batch-оркестраторі — skip, не помилка прогону).
+ * @param {string} file абсолютний шлях джерела
+ * @param {{ existingMd?: string|null }} [opts] наявна дока (для захищеної секції «Призначення»)
+ * @returns {Promise<{ facts: object, anchors: object|null, src: string, messages: Array<{role:string,content:string}>, intent: string|null }>} усе потрібне для item-у batch-у й пізнішого фінішу
+ */
+export async function prepareBatchItem(file, { existingMd = null } = {}) {
+  const { src, facts } = await loadSrcAndFacts(file)
+  const anchors = facts.unsupported ? null : extractAnchors(src)
+  const intent = existingMd ? splitProtected(existingMd).body : null
+  return { facts, anchors, src, messages: oneShotMessages(facts, src), intent }
+}
+
+/**
+ * T8 (2b-batch): постобробка ОДНОГО результату `submitBatch` — той самий фініш,
+ * що й `oneShotDoc`/`finishUnsupported`/det-скорер, тільки без LLM-виклику
+ * (текст уже отримано з batch-у). Judge-гейт (Stage 3) у batch-шляху НЕ
+ * викликається (мінімальний обсяг T8 — генерація; judge лишається опційним
+ * розширенням послідовного шляху).
+ * @param {string} text сирий текст відповіді моделі для цього item-у
+ * @param {{ facts: object, anchors: object|null, src: string, intent: string|null, model: string, threshold?: number }} ctx контекст item-у (з `prepareBatchItem`)
+ * @returns {{ md: string, score: number|null, issues: string[], degraded: boolean, model: string }} результат генерації для штампу/запису
+ */
+export function finishBatchItem(text, { facts, anchors, src, intent, model, threshold = QUALITY_THRESHOLD }) {
+  let md = stripSignatures(stripSection(text))
+  if (!md.startsWith('#')) md = `# ${basename(facts.relPath)}\n\n${md}`
+  md = insertProtected(md + '\n', intent)
+  if (facts.unsupported) {
+    const refusal = detectRefusalFiller(splitProtected(md).without)
+    return {
+      md,
+      score: refusal ? 0 : null,
+      issues: refusal ? ['refusal-filler'] : [],
+      degraded: Boolean(refusal),
+      model
+    }
+  }
+  const { score, issues } = scoreDoc(md, facts, { anchors, src })
+  return { md, score, issues, degraded: score < threshold, model }
+}
+
 // CLI: node docgen-gen.mjs <file> [--model <m>]
 if (isRunAsCli(import.meta.url)) {
   const args = process.argv.slice(2)

package/rules/test/coverage/fix-worker.mjs

@@ -75,6 +75,8 @@ export async function fixWorker(violations, ctx, deps = {}) {
 
   /** @type {string[]} */
   const touchedFiles = []
+  /** @type {Array<{provider: string, hook: string, files: string[], error: string}>} */
+  const failed = []
   /**
    * Викликає опційний fix-hook провайдера, збирає touchedFiles; виняток хука не
    * валить решту хуків/провайдерів — success визначає canonical re-detect.
@@ -88,6 +90,12 @@ export async function fixWorker(violations, ctx, deps = {}) {
     try {
       const res = await provider[hook]({ ...args, cwd: ctx.cwd, ctx: hookCtx(ctx, deadlineAt) })
       touchedFiles.push(...(res?.touchedFiles ?? []))
+      for (const failure of res?.failed ?? []) {
+        const error = failure?.error ?? 'невідома причина'
+        const files = failure?.files ?? []
+        failed.push({ provider: provider.id, hook, files, error })
+        console.warn(`⚠ coverage fix-worker: ${provider.id}.${hook} failed/no-op: ${error}`)
+      }
     } catch (error) {
       console.warn(
         `⚠ coverage fix-worker: ${provider.id}.${hook} впав: ${String(error?.message ?? error).slice(0, 200)}`
@@ -107,5 +115,5 @@ export async function fixWorker(violations, ctx, deps = {}) {
     }
   }
 
-  return { touchedFiles }
+  return { touchedFiles, failed }
 }

package/rules/test/coverage/lib/classify/verdict-schema.mjs

@@ -9,7 +9,9 @@
  *   - glue:          CLI entry / runStandardRule wrapper (integration covers)
  *   - wrapper:       тонкий spawn/fetch wrapper (integration covers)
  */
-import { z } from 'zod'
+// Namespace import сумісний із Bun+Vitest трансформацією Zod 4, де named `z`
+// може бути undefined попри наявність у runtime ESM namespace.
+import * as z from 'zod'
 
 // Трохи ширше за prompt-ліміт (500) — запас на моделі, які трохи перевищують
 // інструкцію; понад це вже truncate-имо самі перед валідацією (REASON_SOFT_MAX нижче).

package/scripts/docs/skills-cli.md

@@ -3,34 +3,28 @@ type: JS Module
 title: skills-cli.mjs
 resource: npm/scripts/skills-cli.mjs
 docgen:
-  crc: 3e5781e6
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 9b3e0ad4
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 25
+  issues: no-overview,short-behavior,internal-name:runTazeOrchestratorCli,anchor-miss:tsconfig.json,anchor-miss:.n-rules.json,anchor-miss:.n-cursor.json,anchor-miss:main.json,best-of-2:retry-lost
 ---
 
-## Огляд
-
-Цей модуль забезпечує керування функціоналом скілів пакета `@7n/rules`. Він каталогізує доступні скіли на основі наявності файлу `SKILL.md` у відповідному пакеті. Для виконання скілу збирається контекст, що включає інструкції скілу та інформацію з конфігураційних файлів проєкту: `package.json`, `tsconfig.json`, `.n-rules.json` та `main.json`. Система дозволяє або вивести список доступних скілів (`npx @7n/rules skill list`), або ініціювати виконання обраного скілу (наприклад, `npx @7n/rules skill pi taze`), з можливістю передачі додаткових аргументів. Пріоритетним механізмом виконання є інтеграція з вбудованим pi-агентом; поряд з ним підтримуються повноцінні зовнішні ACP-агенти (`cursor`, `codex`) і deprecated `claude`.
-
-## Поведінка
-
-Поведінка
-normalizeSkillId знімає префікс `n-` з імені скілу для приведення його до стандартного ID.
-listSkillIds отримує відсортований список ID скілів, які мають файл `SKILL.md` у вказаній директорії скілів.
-buildSkillPrompt збирає комплексний промпт для виконання скілу, об'єднуючи інструкцію скілу з конфігураційними файлами проєкту, такими як `package.json`, `tsconfig.json` та `.n-rules.json`.
-resolveBundledPackageRoot визначає абсолютний шлях до кореня пакету `@7n/rules`, використовуючи інформацію про поточний модуль.
-runSkillsCli виконує логіку командного інтерфейсу для керування скілами: може вивести список доступних скілів, зібрати промпт для скілу або ініціювати його виконання через вбудований pi-агент чи один із зовнішніх CLI-раннерів (`cursor`, `codex`, `claude`).
-
 ## Публічний API
 
-- normalizeSkillId — знімає префікс `n-` з імені скілу, приводячи його до id каталогу в пакеті.
-- listSkillIds — повертає відсортований список id скілів, що мають `SKILL.md`.
-- buildSkillPrompt — збирає промпт виконання: інструкція скілу + контекст проєкту (`package.json`, `tsconfig.json`, `.n-rules.json`); кидає, якщо скіл невідомий.
-- resolveBundledPackageRoot — абсолютний шлях до кореня встановленого пакета `@7n/rules`.
-- runSkillsCli — асинхронний entrypoint підкоманди `skill`: `list`, друк промпта на stdout, або виконання через `pi` (рекомендовано), `cursor`/`codex` (зовнішні CLI), `claude` (deprecated). Повертає exit-код.
+- resolveBundledPackageRoot — Корінь пакета `@7n/rules` (каталог з `skills/`, `rules/`, …).
+- isTazeOrchestratorSkillArgs — Чи `argv` (аргументи після `skill`) резолвиться в JS-оркестрований
+worktree-only `taze`-шлях (`runTazeOrchestratorCli`) — той самий критерій,
+що й нижче в `runSkillsCli`. Використовується `n-rules.js`, щоб не мутувати
+root `package.json` (self-upgrade `@7n/rules`) ДО власного worktree-гейту
+оркестратора: той сам створює worktree і перевіряє чистоту дерева
+(`ensureRunningInWorktree`, `requireCleanTree: true`) — мутація package.json
+прямо перед цим викликом примусово провалила б auto-create там, де дерево
+інакше було б чисте.
+- isJsOrchestratedSkillArgs — Чи аргументи ведуть у будь-який JS-оркестрований skill. Потрібно верхньому
+CLI, щоб не мутувати root package.json self-upgrade-ом до власного preflight
+оркестратора.
 
 ## Гарантії поведінки
 
-- Сам модуль лише читає файли й збирає промпт; **виконання** делегується агенту: `pi` (вбудований, мутує дерево, запускає bash) або зовнішньому ACP-агенту `cursor`/`codex`/`claude` через `runAcpRunner` (`./lib/acp-runner.mjs`) — JSON-RPC поверх stdio (`cursor-agent acp`, бандловані адаптери `@agentclientprotocol/codex-acp` і `@agentclientprotocol/claude-agent-acp`), а не сирий `stdin`/`stdout`-піпінг.
-- Тира моделі для `pi`-runner береться з `main.json.tier` скіла (дефолт `max`).
-- ACP-раннер автоапрувляє `session/request_permission` (без інтерактивних питань) — паритет із колишнім non-interactive режимом; `Client`-реалізація читає/пише файли напряму через `node:fs`.
-- Лише `claude` — deprecated: друкує попередження й лишається як fallback, доки не налаштовано pi-модель. `cursor`/`codex` — повноцінні раннери без попередження.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/scripts/lib/acp-runner.mjs

@@ -3,7 +3,7 @@
  * agentclientprotocol.com) — JSON-RPC поверх stdio.
  *
  * `cursor`/`codex` мігрували на `@7n/llm-lib/acp` (napi-міст до
- * `llm_cascade::acp` — та сама протокольна логіка, але в Rust, без
+ * `llm_lib::acp` — та сама протокольна логіка, але в Rust, без
  * дублювання в JS). `claude` лишається тут як окремий JS-шим, бо Rust-крейт
  * `AcpAgentKind` його не моделює (лише `Cursor`/`Codex`); підʼєднання йде
  * через офіційний TS SDK `@zed-industries/agent-client-protocol`, а дозволи

package/scripts/lib/lint-surface/collateral-veto.mjs

@@ -1,6 +1,8 @@
 /**
  * Semantic-collateral veto для verdict-фази fix-pipeline
- * (spec docs/specs/2026-06-26-pi-fix-engine-migration.md §12, addendum 2026-07-05).
+ * (spec docs/specs/2026-06-26-pi-fix-engine-migration.md §12, addendum 2026-07-05;
+ * in-file hunk-level розширення — addendum 2026-07-24 після колатеральної правки, що
+ * видалила задокументований обхід реального Bun SQL бага в upsert-order.js).
  *
  * Клас collateral слабких локальних моделей: «виправляючи» правило, модель робить
  * семантичну правку у сторонньому файлі, яка НЕ порушує жодного правила й тому
@@ -12,6 +14,15 @@
  * їх однаково покриває re-check зачеплених файлів і rollback. Порожній target-set
  * (whole-repo концерни без `file` у violations) → veto незастосовний (fail-open,
  * повертає []) — свідомо, щоб не ламати концерни без file-атрибуції.
+ *
+ * Другий клас collateral (§12 addendum 2026-07-24): rung змінює файл, що ВЖЕ входить
+ * у target-set (легітимна ціль порушення), але зачіпає рядки поза ділянкою самого
+ * порушення — напр. LLM виправляє відсутній JSDoc над функцією і заодно видаляє сусідній
+ * задокументований обхід реального бага усередині тіла тієї самої функції. Cross-file
+ * veto вище цього не бачить (файл — законна ціль). {@link findInFileCollateralEdits}
+ * рахує грубий (common-prefix/common-suffix, не повний Myers-diff) змінений рядковий
+ * діапазон і звіряє його з вікном навколо кожної `violation.data.line` того ж файлу;
+ * fail-open, якщо рядок порушення невідомий (немає як відповідально обмежити hunk).
  */
 import { realpathSync } from 'node:fs'
 import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
@@ -37,6 +48,18 @@ export function realpathBestEffort(p) {
   }
 }
 
+/**
+ * Нормалізує target-set порушення у множину realpath-абсолютних шляхів — спільна
+ * основа і для collateral-veto (файли ПОЗА target-set), і для test-gate
+ * (файли ВСЕРЕДИНІ target-set, для яких перевіряються сестринські тести).
+ * @param {string[]} targetFiles Файли порушення, відносні до cwd або абсолютні.
+ * @param {string} cwd Робоча директорія для резолву відносних шляхів.
+ * @returns {Set<string>} Нормалізовані абсолютні шляхи target-set (може бути порожньою).
+ */
+export function resolveTargetSet(targetFiles, cwd) {
+  return new Set(targetFiles.map(f => realpathBestEffort(isAbsolute(f) ? f : resolve(cwd, f))))
+}
+
 /**
  * Обчислює collateral-правки rung-а: наявні (на момент S1) файли, змінені поза
  * target-set порушення. Runner на непорожньому результаті відхиляє clean-вердикт
@@ -49,7 +72,60 @@ export function realpathBestEffort(p) {
  *   veto не спрацював (нема collateral або target-set невідомий)
  */
 export function findCollateralEdits({ modifiedExisting, targetFiles, cwd }) {
-  const targets = new Set(targetFiles.map(f => realpathBestEffort(isAbsolute(f) ? f : resolve(cwd, f))))
+  const targets = resolveTargetSet(targetFiles, cwd)
   if (targets.size === 0) return []
   return modifiedExisting.map(p => realpathBestEffort(p)).filter(abs => !targets.has(abs))
 }
+
+/** Дефолтне вікно (рядків з обох боків `violation.data.line`), у межах якого зміна вважається «поруч із порушенням». */
+export const HUNK_WINDOW = 20
+
+/**
+ * Обчислює грубий змінений рядковий діапазон (1-indexed, у координатах `current`) між
+ * pre-image і поточним вмістом файлу: найдовший спільний префікс + найдовший спільний
+ * суфікс рядків, все між ними — «змінене». Це НЕ повний diff (не бачить кількох
+ * розрізнених hunk-ів як окремих інтервалів — лише зовнішні межі першої і останньої
+ * розбіжності), але достатньо, щоб відрізнити «зміна лишилась у ділянці порушення» від
+ * «зачепило щось далеко» — для повного Myers-diff тут немає залежності, а точність
+ * hunk-рівня явно позначена як бажаний, але не обов'язковий бар (spec §12 addendum
+ * 2026-07-24).
+ * @param {string} preImage Вміст файлу на момент S1.
+ * @param {string} current Поточний вміст файлу.
+ * @returns {{ start: number, end: number }|null} діапазон зміни, або null якщо вміст ідентичний.
+ */
+function changedLineRange(preImage, current) {
+  if (preImage === current) return null
+  const preLines = preImage.split('\n')
+  const curLines = current.split('\n')
+  const maxLcp = Math.min(preLines.length, curLines.length)
+  let lcp = 0
+  while (lcp < maxLcp && preLines[lcp] === curLines[lcp]) lcp++
+  const maxLcs = maxLcp - lcp
+  let lcs = 0
+  while (lcs < maxLcs && preLines[preLines.length - 1 - lcs] === curLines[curLines.length - 1 - lcs]) lcs++
+  const start = lcp + 1
+  const end = curLines.length - lcs
+  return start > end ? null : { start, end }
+}
+
+/**
+ * In-file hunk-level veto (§12 addendum 2026-07-24): rung змінив файл, що вже входить
+ * у target-set порушення, але змінений рядковий діапазон виходить за межі вікна навколо
+ * КОЖНОЇ `violation.data.line` цього файлу — сигнал колатеральної правки поза власне
+ * порушенням (клас upsert-order.js: LLM видалив сусідній задокументований обхід бага,
+ * виправляючи doc-comment над функцією). Fail-open: якщо для файлу немає жодного
+ * порушення з відомим `line`, hunk неможливо відповідально обмежити — повертає null.
+ * @param {{ preImage: string|null, current: string|null, violationLines: number[], window?: number }} args
+ *   preImage/current — вміст файлу до/після rung-а; violationLines — номери рядків
+ *   порушень ЦЬОГО rung-а в ЦЬОМУ файлі; window — половина ширини допустимого вікна.
+ * @returns {{ start: number, end: number }|null} діапазон відхиленої правки, або null —
+ *   veto не спрацював (нема зміни, зміна в межах вікна, або невідома локація порушення).
+ */
+export function findInFileCollateralEdits({ preImage, current, violationLines, window = HUNK_WINDOW }) {
+  if (preImage === null || preImage === undefined || current === null || current === undefined) return null
+  if (!violationLines || violationLines.length === 0) return null
+  const range = changedLineRange(preImage, current)
+  if (!range) return null
+  const inWindow = violationLines.some(line => range.start >= line - window && range.end <= line + window)
+  return inWindow ? null : range
+}

package/scripts/lib/lint-surface/docs/collateral-veto.md

@@ -3,26 +3,40 @@ type: JS Module
 title: collateral-veto.mjs
 resource: npm/scripts/lib/lint-surface/collateral-veto.mjs
 docgen:
-  crc: 16d3ef02
+  crc: 96d4ee38
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-## Огляд
-
-Semantic-collateral veto для verdict-фази fix-pipeline (spec pi-fix-engine-migration §12, addendum 2026-07-05). Закриває клас collateral слабких локальних моделей: «виправляючи» правило, модель робить семантичну правку у сторонньому файлі, яка не порушує жодного правила й тому проходить canonical re-detect (кейс App.vue: хардкод версії з коментарем «we simulate it being available» замість виклику `getVersion`).
-
-## Поведінка
-
-1. `findCollateralEdits` порівнює список змінених наявних файлів rung-а (`snapshot.modifiedExisting()`) із target-set порушення (`violations[].file ∪ item.files`) і повертає правки поза target-set.
-2. Нові файли до veto не входять — легітимний клас (scaffold, доки поряд із кодом); їх покриває re-check зачеплених файлів і rollback.
-3. Порожній target-set (whole-repo концерни без `file` у violations) → veto незастосовний: свідомий fail-open, повертається порожній масив.
-4. Усі шляхи realpath-нормалізуються (`realpathBestEffort`, той самий патерн, що у write-guard llm-lib) — знімає symlink-розбіжності macOS (`/tmp` → `/private/tmp`); caller relativize-ить результати від так само нормалізованого cwd.
-
 ## Публічний API
 
-- `findCollateralEdits({ modifiedExisting, targetFiles, cwd })` — нормалізовані абсолютні шляхи відхилених правок; порожньо — collateral немає або target-set невідомий.
-- `realpathBestEffort(p)` — realpath з найкращих зусиль (наявний файл → повний realpath; неіснуючий → realpath батьківської теки + basename; інакше — як є).
+- realpathBestEffort — realpath шляху з найкращих зусиль: для наявного — повний realpath; для ще-неіснуючого —
+realpath батьківської теки + basename; інакше — як є. Знімає розбіжність symlink-шляхів
+(macOS `/tmp` → `/private/tmp`) між snapshot-ключами і target-set (той самий патерн,
+що у write-guard llm-lib). Експортовано, щоб caller relativize-ив результати veto від
+так само нормалізованого cwd.
+- resolveTargetSet — Нормалізує target-set порушення у множину realpath-абсолютних шляхів — спільна
+основа і для collateral-veto (файли ПОЗА target-set), і для test-gate
+(файли ВСЕРЕДИНІ target-set, для яких перевіряються сестринські тести).
+- findCollateralEdits — Обчислює collateral-правки rung-а: наявні (на момент S1) файли, змінені поза
+target-set порушення. Runner на непорожньому результаті відхиляє clean-вердикт
+rung-а (rollback + feedback + телеметрія `kind:"collateral-veto"`).
+  modifiedExisting — абсолютні шляхи наявних файлів, змінених відносно S1
+  (`snapshot.modifiedExisting()`); targetFiles — файли порушення
+  (`violations[].file ∪ item.files`), відносні до cwd або абсолютні.
+- HUNK_WINDOW — Дефолтне вікно (рядків з обох боків `violation.data.line`), у межах якого зміна вважається «поруч із порушенням».
+- findInFileCollateralEdits — In-file hunk-level veto (§12 addendum 2026-07-24): rung змінив файл, що вже входить
+у target-set порушення, але змінений рядковий діапазон виходить за межі вікна навколо
+КОЖНОЇ `violation.data.line` цього файлу — сигнал колатеральної правки поза власне
+порушенням (клас upsert-order.js: LLM видалив сусідній задокументований обхід бага,
+виправляючи doc-comment над функцією). Fail-open: якщо для файлу немає жодного
+порушення з відомим `line`, hunk неможливо відповідально обмежити — повертає null.
+  preImage/current — вміст файлу до/після rung-а; violationLines — номери рядків
+  порушень ЦЬОГО rung-а в ЦЬОМУ файлі; window — половина ширини допустимого вікна.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
-- Ніколи не кидає: помилки realpath ігноруються з поверненням шляху як є.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -24,6 +24,7 @@ resource: npm/scripts/lib/lint-surface/
 | [run-fix.mjs](run-fix.md)                                   | JS Module |
 | [scheduler.mjs](scheduler.md)                               | JS Module |
 | [snapshot.mjs](snapshot.md)                                 | JS Module |
+| [test-gate.mjs](test-gate.md)                               | JS Module |
 | [tier-sampling-bench.mjs](tier-sampling-bench.md)           | JS Module |
 | [tier-sampling-experiment.mjs](tier-sampling-experiment.md) | JS Module |
 | [types.mjs](types.md)                                       | JS Module |

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

@@ -3,33 +3,18 @@ type: JS Module
 title: run-fix.mjs
 resource: npm/scripts/lib/lint-surface/run-fix.mjs
 docgen:
-  crc: 45965f7d
-  model: manual
+  crc: 7f20adb7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 50
+  issues: no-overview,short-behavior,anchor-miss:.mt.json,best-of-2:retry-lost
 ---
 
-## Огляд
-
-Цей файл реалізує уніфіковану поверхню для фіксації порушень лінтування (unified lint surface) відповідно до специфікації `2026-06-29 §Fix Role / §Tier Ladder`. Він керує послідовним процесом виявлення та усунення проблем, який складається з етапів: виявлення → (очищення/збереження) → Т0 (перманентне виправлення) → знімок S1 → повторне виявлення → (очищення/збереження) → цикл `ladder[відновлення S1 → worker → виявлення]*` (до вичерпання) → (вичерпання/відкат S1). Публічна функція `fixConcern` відповідає за індивідуальне виправлення певного компонента, а `runFixPipeline` ініціює весь комплексне виконання пайплайну. Ролі є чітко розподілені: `detector` лише виявляє, тоді як `T0` та `worker` здійснюють зміни. Успішне завершення визначається виключно канонічним повторним виявленням.
-
-## Поведінка
-
-Поведінка:
-fixConcern застосовує детерміновані патерни (T0), а потім, якщо це можливо, послідовно виконує ланцюжок фікс-операцій (ladder) для виявлення та усунення порушень певного concern-а.
-runFixPipeline керує повним циклом виправлення: він детектирує всі порушення, застосовує виправлення для кожного знайденого concern-а через `fixConcern`, і виводить фінальний звіт про нездоланні порушення.
-Per-tier timeout (ADR 260620-0556): кожен rung передає worker-у свій `timeoutMs` через `FixContext` (шлях до `runAgentFix opts.timeoutMs`, який abort-ить LLM-сесію), а сам виклик worker-а додатково огорнутий backstop-гонкою ×1.25 від `rung.timeoutMs` — worker, що ігнорує таймаут (зокрема зависла cloud-SSE), фейлить rung помилкою `fix timeout …` замість блокувати lint назавжди; така помилка класифікується як quality і ladder ескалює далі.
-Semantic-collateral veto (spec pi-fix-engine-migration §12, addendum 2026-07-05): clean-вердикт rung-а не приймається, якщо rung змінив наявні файли поза target-set порушення (`violations[].file ∪ item.files`, звірка через `collateral-veto.mjs` за `snapshot.modifiedExisting()`); наслідок — rollback S1, `🚫`-лог, feedback наступному rung-у й телеметрія `kind:"collateral-veto"` у глобальний llm-trace. Нові файли дозволені; порожній target-set → veto незастосовний (fail-open).
-Evidence-гейт рунга (Фаза A1 run-harness, спека 2026-07-11): кожен rung отримує у `FixContext` `verify` — item-scoped canonical re-detect (той самий детектор, що й фінальний вердикт), і `verifyMax` per tier (local — 1, cloud — 2); worker прокидає їх у `runAgentFix`, де провал verify інʼєктиться фідбеком у ту саму pi-сесію. Зовнішній canonical re-detect після worker-а лишається єдиним вердиктом рунга; помилка детектора всередині verify ковтається у `{ok:false}` — зовнішній detect кине її штатно.
-Durable-write-и (issue nitra/cursor#16): worker отримує у `FixContext` поруч із `recordWrite` опційний `recordDurableWrite` — для записів, кожен з яких є самодостатнім кінцевим станом (doc-files: дока зі свіжим CRC). Такі файли переживають rollback провального rung-а і не входять у collateral-veto: частковий прогрес великого батчу не стирається, canonical re-detect наступного rung-а/прогону рахує лише те, що реально лишилось.
-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
 
-fixConcern — Виконує один етап перевірки у конвеєрі (T0 → S1 → ladder) та повідомляє про результат закриття цієї перевірки.
-runFixPipeline — Запускає повний цикл виправлення: ідентифікує всі проблеми, виправляє кожну, що не пройшла перевірку, і завершує роботу.
+- fixConcern — Проводить ОДИН concern по pipeline: T0 → S1 → ladder. Повертає чи закрито.
+- runFixPipeline — Повний fix-pipeline: detect усе → fix кожен провальний concern → exit code.
 
 ## Гарантії поведінки
 
-- Сам не редагує кодові файли (мутації роблять T0/worker); пише лише телеметрію collateral-veto у глобальний llm-trace (best-effort, ніколи не валить прогін).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

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

@@ -3,27 +3,16 @@ type: JS Module
 title: snapshot.mjs
 resource: npm/scripts/lib/lint-surface/snapshot.mjs
 docgen:
-  crc: 4a2fab06
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
+  crc: 949c1cac
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 55
+  issues: no-overview,short-behavior,best-of-2:retry-lost
 ---
 
-## Огляд
-
-Централізований знімок попереднього образу (pre-image snapshot) та механізм відкату (rollback) забезпечують функціональність фікс-пайплайну відповідно до специфікації spec 2026-06-29, §Tier Ladder. Відкат відновлює попередній стан файлів, але не видаляє ті, що відсутні у знімку. Операції виконуються послідовно для кожного окремого concern-а, гарантуючи, що стан кожного concern-а базується на успішних змінах попередніх concern-ів. До запису в tracker.record ПЕРЕД мутацією забезпечується фіксація попереднього образу для кожного потенційно зміненого файлу. Окремо підтримуються durable-write-и — самодостатні кінцеві стани (напр. файлові доки зі свіжим CRC), які rollback не чіпає.
-
-## Поведінка
-
-1. Створюється об'єкт-трекер попереднього стану. Цей трекер фіксує вихідний стан файлів, які можуть бути змінені в процесі виправлення.
-2. Для фіксації стану файлу використовується механізм `record`, який зберігає вміст файлу або маркер відсутності, якщо файл на момент фіксації не існував.
-3. Механізм `recordDurable` позначає шлях як durable: запис у такий файл — самодостатній кінцевий стан, тож rollback його не відновлює й не видаляє, а semantic-collateral veto його не враховує. Це дозволяє batch-worker-ам (doc-files) зберігати частковий прогрес після провалу/таймауту rung-а — беклог сходиться за кілька прогонів (issue nitra/cursor#16).
-4. Після виконання змін, трекеру викликається `rollback`. Цей метод відновлює вміст усіх зафіксованих файлів (крім durable-позначених), а файли, які відсутні на момент фіксації, видаляє.
-5. Щоб отримати список усіх файлів, чий попередній стан був зафіксований або які позначені durable, використовується метод `touched`.
-6. Метод `modifiedExisting` повертає наявні на момент S1 файли, чий поточний вміст відрізняється від pre-image (видалення наявного файлу теж вважається зміною) — вхід semantic-collateral veto; нові файли та durable-шляхи до результату не входять.
-
 ## Публічний API
 
-- createSnapshot — створює фіксацію стану (snapshot S1) з порожнім набором попередніх зображень.
+- createSnapshot — Створює tracker зі свіжим (порожнім) набором pre-images — це і є snapshot S1.
 
 ## Гарантії поведінки