@7n/rules 1.48.2 → 1.49.1

package/scripts/lib/lint-surface/docs/test-gate.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: test-gate.mjs
+resource: npm/scripts/lib/lint-surface/test-gate.mjs
+docgen:
+  crc: 212d387b
+  model: manual
+---
+
+## Огляд
+
+Test-gate верифікація для non-T0 (LLM) fix-ladder rung-ів (spec addendum 2026-07-24, ladder-collateral-in-file). Закриває клас колатеральних правок, які [collateral-veto.mjs](./collateral-veto.md) не бачить: правки ВСЕРЕДИНІ вже-таргетованого файлу (напр. видалення задокументованого workaround поруч із фіксованим порушенням) не зачіпають жодного детектора й не торкаються файлів поза target-set, тож проходять і collateral-veto, і canonical re-detect. Якщо для зміненого файлу з target-set існує сестринський тест-файл за конвенцією `<dir>/tests/<stem>.test.{mjs,js,ts}` (n-test.mdc), той тест виконується як частина verify — провал тесту відхиляє clean-вердикт rung-а так само, як і collateral-veto.
+
+## Поведінка
+
+1. `findSiblingTestFiles(sourceAbsPath)` конструює кандидатів `<dir>/tests/<stem>.test.{mjs,js,ts}` для джерела з розширенням `.mjs`/`.js`/`.ts`/`.vue` і повертає лише наявні на диску файли.
+2. `runTestFile(testAbsPath, cwd)` виконує один тест-файл через `bunx vitest run --reporter=verbose <file>` (`spawnSync`, таймаут 30s). Fail-open: spawn-помилка, відсутній `bunx`/vitest, чи таймаут (`status === null`) — повертає `passed: true`, а не блокує rung.
+3. `findBrokenSiblingTests({ files, cwd, runTest })` перебирає файли (наявні, у target-set, реально змінені rung-ом), для кожного шукає сестринські тести й запускає перший знайдений; перший провал зупиняє пошук і повертається як veto-кандидат. `runTest` — override test-runner-а для юніт-тестів цього модуля (типово `runTestFile`).
+
+## Публічний API
+
+- `findSiblingTestFiles(sourceAbsPath)` — наявні сестринські тест-файли джерела (може бути порожньо).
+- `runTestFile(testAbsPath, cwd)` — `{ passed, output }`, fail-open на інфраструктурну помилку.
+- `findBrokenSiblingTests({ files, cwd, runTest? })` — `{ file, testFile, output } | null`, перший зафіксований провал.
+
+## Гарантії поведінки
+
+- Fail-open за дизайном: відсутній test-runner, таймаут чи відсутність сестринського тесту ніколи не блокує fix-ladder.
+- Не редагує жодних файлів — лише читає (пошук тест-файлів) і запускає сторонній процес (vitest).

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

@@ -14,8 +14,8 @@
  * @typedef {import('./run-detectors.mjs').PlanItem} PlanItem
  * @typedef {import('./ladder.mjs').Rung} Rung
  */
-import { existsSync } from 'node:fs'
-import { join, relative } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { LOCAL_MIN, CLOUD_MIN, CLOUD_AVG, isLocalModel } from '@7n/llm-lib/model-tiers'
@@ -26,7 +26,13 @@ import { buildDetectPlan } from './run-detectors.mjs'
 import { runConcernDetector, DetectorError } from './detect.mjs'
 import { renderViolations } from './render.mjs'
 import { createSnapshot } from './snapshot.mjs'
-import { findCollateralEdits, realpathBestEffort } from './collateral-veto.mjs'
+import {
+  findCollateralEdits,
+  findInFileCollateralEdits,
+  realpathBestEffort,
+  resolveTargetSet
+} from './collateral-veto.mjs'
+import { findBrokenSiblingTests } from './test-gate.mjs'
 import { createProgressReporter } from './progress.mjs'
 import { buildLadder, decideAfterFailure, DEFAULT_MAX_AVG } from './ladder.mjs'
 
@@ -174,6 +180,168 @@ async function runT0Phase(item, initialViolations, patterns, lintCtx, cwd, log,
  * @typedef {{ action: 'break'|'skip-model'|null, violations: LintViolation[], feedback: FixFeedback }} RungOutcome
  */
 
+/**
+ * Cross-file (§12 addendum 2026-07-05) + in-file hunk-level (addendum 2026-07-24)
+ * collateral rung-а: наявні файли, змінені поза target-set, і наявні файли ВСЕРЕДИНІ
+ * target-set, змінені поза вікном навколо `violation.data.line`. Чиста функція (без
+ * трейсу/side-effects) — виклик trace лишається на caller-і.
+ * @param {{ violations: LintViolation[], item: PlanItem, snapshot: ReturnType<typeof createSnapshot>, cwd: string }} args Порушення rung-а, елемент плану, snapshot S1 і робоча директорія.
+ * @returns {{ targetFiles: string[], collateral: string[], inFileHunks: Array<{ file: string, start: number, end: number }>, collateralAll: string[], rejectedRel: string[], inFileHunkRel: string[] }} Обидва класи collateral (cross-file, in-file) і їхнє відносне представлення для логу/feedback.
+ */
+function computeCollateral({ violations, item, snapshot, cwd }) {
+  // Semantic-collateral veto (§12 addendum 2026-07-05): clean-вердикт не приймається,
+  // якщо rung ЗМІНИВ наявні файли поза target-set порушення (клас «App.vue: хардкод
+  // версії замість getVersion»). Нові файли дозволені (scaffold/доки); порожній
+  // target-set (whole-repo концерни без file-атрибуції) → veto незастосовний.
+  const targetFiles = [...new Set([...violations.map(v => v.file).filter(Boolean), ...(item.files ?? [])])]
+  const collateral = findCollateralEdits({ modifiedExisting: snapshot.modifiedExisting(), targetFiles, cwd })
+
+  // In-file hunk-level veto (§12 addendum 2026-07-24): файл — легітимна ціль, але rung
+  // зачепив рядки поза вікном навколо порушень ЦЬОГО файлу (upsert-order.js: doc-comment
+  // fix + сусіднє видалення intentional-workaround-у, невидиме для cross-file veto вище).
+  // Без realpath: snapshot-ключі — це те, що воркер сам передав у recordWrite (як правило
+  // `join(cwd, relFile)`), і `resolve(cwd, v.file)` дає той самий рядок за тим самим
+  // (не-realpath-нормалізованим) cwd — realpath тут лише зіпсував би збіг ключів мапи.
+  const violationLinesByFile = new Map()
+  for (const v of violations) {
+    const line = v.data?.line
+    if (!v.file || typeof line !== 'number') continue
+    const abs = isAbsolute(v.file) ? v.file : resolve(cwd, v.file)
+    if (!violationLinesByFile.has(abs)) violationLinesByFile.set(abs, [])
+    violationLinesByFile.get(abs).push(line)
+  }
+  const modifiedAbs = new Set(snapshot.modifiedExisting())
+  const inFileHunks = []
+  for (const [abs, lines] of violationLinesByFile) {
+    if (!modifiedAbs.has(abs)) continue
+    const pre = snapshot.preImageOf(abs)
+    if (pre === null) continue
+    let current
+    try {
+      current = existsSync(abs) ? readFileSync(abs, 'utf8') : null
+    } catch {
+      continue
+    }
+    const hunk = findInFileCollateralEdits({ preImage: pre, current, violationLines: lines })
+    if (hunk) inFileHunks.push({ file: abs, ...hunk })
+  }
+
+  const collateralAll = [...collateral, ...inFileHunks.map(h => h.file)]
+  // relative — від так само realpath-нормалізованого cwd, інакше symlink-cwd (macOS
+  // /var → /private/var) дає `../../…`-шляхи у телеметрії та feedback.
+  const rejectedRel = collateral.map(p => relative(realpathBestEffort(cwd), p))
+  const inFileHunkRel = inFileHunks.map(h => `${relative(realpathBestEffort(cwd), h.file)}:${h.start}-${h.end}`)
+  return { targetFiles, collateral, inFileHunks, collateralAll, rejectedRel, inFileHunkRel }
+}
+
+/**
+ * Test-gate (addendum 2026-07-24): collateral-veto (cross-file + in-file hunk) вище
+ * ловить лише правки, видимі як diff проти S1. Правки ВСЕРЕДИНІ вже-таргетованого
+ * файлу, у ВІКНІ навколо violation.data.line (тому не зловлені in-file hunk-level
+ * veto), теж можуть зламати наявний проєктний тест — test-gate це третій, незалежний
+ * рубіж. Скоуп — лише наявні файли ВСЕРЕДИНІ target-set, реально змінені цим rung-ом
+ * (не колатеральні — ті вже відхилені collateral-veto); caller пропускає виклик, якщо
+ * collateralAll уже ветував rung (нема сенсу гонити тести на приреченому rung-у).
+ * Fail-open (findBrokenSiblingTests сама fail-open на відсутність test-runner-а/
+ * таймаут/відсутність сестринського тесту). Побічний ефект: пише trace на провал.
+ * @param {{ targetFiles: string[], snapshot: ReturnType<typeof createSnapshot>, cwd: string, testRunner: typeof import('./test-gate.mjs').runTestFile|undefined, ruleId: string, concernName: string, rung: Rung }} args Файли порушення, snapshot S1, робоча директорія, override test-runner-а і координати rung-а для телеметрії.
+ * @returns {{ file: string, testFile: string, output: string } | null} Перший зафіксований провал сестринського тесту, або null якщо test-gate не спрацював.
+ */
+function detectBrokenTest({ targetFiles, snapshot, cwd, testRunner, ruleId, concernName, rung }) {
+  const targets = resolveTargetSet(targetFiles, cwd)
+  const modifiedInTarget = snapshot
+    .modifiedExisting()
+    .map(p => realpathBestEffort(p))
+    .filter(abs => targets.has(abs))
+  if (modifiedInTarget.length === 0) return null
+  // `runTest: testRunner` — default-параметр findBrokenSiblingTests спрацьовує саме
+  // на `undefined`, тож відсутній override прозоро падає назад на runTestFile.
+  const brokenTest = findBrokenSiblingTests({ files: modifiedInTarget, cwd, runTest: testRunner })
+  if (!brokenTest) return null
+  writeTrace({
+    caller: `fix:${ruleId}/${concernName}:${rung.tier}`,
+    backend: 'pi-ai',
+    kind: 'test-gate-veto',
+    rule: ruleId,
+    rung: rung.tier,
+    model: rung.model,
+    cwd,
+    brokenFile: relative(realpathBestEffort(cwd), brokenTest.file),
+    brokenTestFile: relative(realpathBestEffort(cwd), brokenTest.testFile),
+    targetFiles,
+    cleanDetect: true
+  })
+  return brokenTest
+}
+
+/**
+ * Опис відхиленого rung-а для логу (`errorSuffix`) і feedback наступному rung-у
+ * (`silentFailureNote`) — один пріоритет: worker-помилка → collateral-veto →
+ * test-gate-veto → мовчазна невдача (worker нічого не змінив / змінив, але
+ * порушення лишилось).
+ * @param {object} args Дані одного rung-а, потрібні для опису відхилення.
+ * @param {string|null} args.error Повідомлення worker-помилки, якщо rung кинув виняток.
+ * @param {string[]} args.collateralAll Об'єднаний список відхилених collateral-правок (cross-file abs).
+ * @param {string[]} args.rejectedRel Cross-file collateral (відносні шляхи).
+ * @param {string[]} args.inFileHunkRel In-file hunk-level collateral (`file:start-end`).
+ * @param {{ file: string, testFile: string } | null} args.brokenTest Результат test-gate.
+ * @param {string} args.cwd Робоча директорія (для relative()).
+ * @param {string[]} args.targetFiles Файли порушення rung-а.
+ * @param {string} args.model Модель rung-а (для тексту feedback).
+ * @param {string[]} args.touchedFiles Файли, торкнуті worker-ом.
+ * @returns {{ errorSuffix: string, silentFailureNote: string }} Суфікс для логу і нотатка для feedback наступному rung-у.
+ */
+function describeVetoOutcome({
+  error,
+  collateralAll,
+  rejectedRel,
+  inFileHunkRel,
+  brokenTest,
+  cwd,
+  targetFiles,
+  model,
+  touchedFiles
+}) {
+  if (error) return { errorSuffix: ` ❌ ${error.slice(0, 120)}`, silentFailureNote: '' }
+
+  if (collateralAll.length > 0) {
+    const parts = []
+    if (rejectedRel.length > 0) parts.push(`змінила наявні файли поза target-set (${rejectedRel.join(', ')})`)
+    if (inFileHunkRel.length > 0) parts.push(`зачепила рядки поза ділянкою порушення (${inFileHunkRel.join(', ')})`)
+    return {
+      errorSuffix: ` 🚫 collateral-veto: ${[...rejectedRel, ...inFileHunkRel].join(', ')}`,
+      silentFailureNote:
+        `Попередня спроба (${model}) закрила порушення, але ${parts.join('; ')} — усі правки відхилено. ` +
+        `Редагуй ЛИШЕ рядки порушення у файлах: ${targetFiles.join(', ')}.`
+    }
+  }
+
+  if (brokenTest) {
+    const brokenFileRel = relative(realpathBestEffort(cwd), brokenTest.file)
+    const brokenTestRel = relative(realpathBestEffort(cwd), brokenTest.testFile)
+    return {
+      errorSuffix: ` 🚫 test-gate-veto: ${brokenTestRel}`,
+      silentFailureNote:
+        `Попередня спроба (${model}) закрила порушення, але зламала наявний тест ` +
+        `${brokenTestRel} (файл ${brokenFileRel}) — усі правки відхилено. ` +
+        'Виправ ЛИШЕ саме порушення, не чіпай навколишню логіку/коментарі-попередження.'
+    }
+  }
+
+  if (touchedFiles.length === 0) {
+    return {
+      errorSuffix: ' ❌ досі порушено',
+      silentFailureNote: `Попередня спроба (${model}) не внесла жодної зміни у файли; порушення досі активне.`
+    }
+  }
+  return {
+    errorSuffix: ' ❌ досі порушено',
+    silentFailureNote:
+      `Попередня спроба (${model}) торкнулась файлів (${touchedFiles.join(', ')}), ` +
+      'але порушення досі активне — той самий підхід не спрацював, спробуй інакше.'
+  }
+}
+
 /**
  * Проводить один rung ladder-а: worker → canonical re-detect → rollback при провалі.
  * @param {Rung} rung Поточна сходинка ladder-а.
@@ -187,10 +355,12 @@ async function runT0Phase(item, initialViolations, patterns, lintCtx, cwd, log,
  * @param {(s: string) => void} rungDeps.log Логер.
  * @param {import('./progress.mjs').ProgressReporter|null} [rungDeps.progress] Reporter прогресу.
  * @param {boolean} [rungDeps.verbose] Детальний вивід (прокидається у ctx concern-а).
+ * @param {typeof import('./test-gate.mjs').runTestFile} [rungDeps.testRunner] Override
+ *   test-runner-а для test-gate (інжект для тестів).
  * @returns {Promise<{ closed: true, touchedFiles: string[] } | { closed: false, outcome: RungOutcome }>} closed=true якщо concern закрито (touchedFiles — зміни worker-а); інакше результат для наступного кроку.
  */
 async function runRung(rung, worker, violations, feedback, rungDeps) {
-  const { item, cwd, snapshot, log, progress = null, verbose = false, chain = null } = rungDeps
+  const { item, cwd, snapshot, log, progress = null, verbose = false, chain = null, testRunner } = rungDeps
   const { ruleId } = item.entry
   const concernName = item.entry.concern.name
   progress?.concernStart(progressKey(item), rung.tier)
@@ -252,16 +422,13 @@ async function runRung(rung, worker, violations, feedback, rungDeps) {
     throw detectError
   }
 
-  // Semantic-collateral veto (§12 addendum 2026-07-05): clean-вердикт не приймається,
-  // якщо rung ЗМІНИВ наявні файли поза target-set порушення (клас «App.vue: хардкод
-  // версії замість getVersion»). Нові файли дозволені (scaffold/доки); порожній
-  // target-set (whole-repo концерни без file-атрибуції) → veto незастосовний.
-  const targetFiles = [...new Set([...violations.map(v => v.file).filter(Boolean), ...(item.files ?? [])])]
-  const collateral = findCollateralEdits({ modifiedExisting: snapshot.modifiedExisting(), targetFiles, cwd })
-  // relative — від так само realpath-нормалізованого cwd, інакше symlink-cwd (macOS
-  // /var → /private/var) дає `../../…`-шляхи у телеметрії та feedback.
-  const rejectedRel = collateral.map(p => relative(realpathBestEffort(cwd), p))
-  if (collateral.length > 0) {
+  const { targetFiles, collateralAll, rejectedRel, inFileHunkRel } = computeCollateral({
+    violations,
+    item,
+    snapshot,
+    cwd
+  })
+  if (collateralAll.length > 0) {
     // Телеметрія відхилених правок — той самий глобальний llm-trace, що й fix-виклики.
     writeTrace({
       caller: `fix:${ruleId}/${concernName}:${rung.tier}`,
@@ -272,11 +439,20 @@ async function runRung(rung, worker, violations, feedback, rungDeps) {
       model: rung.model,
       cwd,
       rejectedFiles: rejectedRel,
+      rejectedHunks: inFileHunkRel,
       targetFiles,
       cleanDetect: after.length === 0
     })
   }
-  const vetoed = after.length === 0 && !error && collateral.length > 0
+  // Test-gate: третій, незалежний рубіж поверх collateral-veto (cross-file + in-file
+  // hunk) — пропускається, якщо collateralAll уже ветував rung (нема сенсу гонити
+  // тести на приреченому rung-у).
+  const brokenTest =
+    after.length === 0 && !error && collateralAll.length === 0
+      ? detectBrokenTest({ targetFiles, snapshot, cwd, testRunner, ruleId, concernName, rung })
+      : null
+
+  const vetoed = after.length === 0 && !error && (collateralAll.length > 0 || brokenTest !== null)
   const touchedFiles = workerResult?.touchedFiles ?? []
 
   if (after.length === 0 && !error && !vetoed) {
@@ -301,9 +477,17 @@ async function runRung(rung, worker, violations, feedback, rungDeps) {
     return { closed: true, touchedFiles }
   }
 
-  let errorSuffix = ' ❌ досі порушено'
-  if (error) errorSuffix = ` ❌ ${error.slice(0, 120)}`
-  else if (vetoed) errorSuffix = ` 🚫 collateral-veto: ${rejectedRel.join(', ')}`
+  const { errorSuffix, silentFailureNote } = describeVetoOutcome({
+    error,
+    collateralAll,
+    rejectedRel,
+    inFileHunkRel,
+    brokenTest,
+    cwd,
+    targetFiles,
+    model: rung.model,
+    touchedFiles
+  })
   log(`  ⚡ ${rung.tier} (${rung.model}): ${ruleId}/${concernName}${errorSuffix}\n`)
 
   // Не clean → restore S1 перед наступним rung-ом (degraded не тече далі).
@@ -312,23 +496,6 @@ async function runRung(rung, worker, violations, feedback, rungDeps) {
   // canonical re-detect-ом вище — наступний rung/прогін продовжує з решти, не з нуля.
   snapshot.rollback()
 
-  // Мовчазна невдача (worker не кинув виняток, але порушення лишилось) — без цього
-  // наступний rung стартує без жодного знання про попередню спробу (buildFixPrompt
-  // додає `## Попередня спроба` лише коли previousError truthy).
-  let silentFailureNote
-  if (vetoed) {
-    silentFailureNote =
-      `Попередня спроба (${rung.model}) закрила порушення, але змінила наявні файли поза ` +
-      `target-set (${rejectedRel.join(', ')}) — усі правки відхилено. ` +
-      `Редагуй ЛИШЕ файли порушення: ${targetFiles.join(', ')}.`
-  } else if (touchedFiles.length === 0) {
-    silentFailureNote = `Попередня спроба (${rung.model}) не внесла жодної зміни у файли; порушення досі активне.`
-  } else {
-    silentFailureNote =
-      `Попередня спроба (${rung.model}) торкнулась файлів (${touchedFiles.join(', ')}), ` +
-      'але порушення досі активне — той самий підхід не спрацював, спробуй інакше.'
-  }
-
   return {
     closed: false,
     outcome: {
@@ -374,6 +541,8 @@ function summarizeProblem(violations) {
  * @param {import('./progress.mjs').ProgressReporter|null} [deps.progress] Reporter прогресу.
  * @param {boolean} [deps.verbose] Детальний вивід (прокидається у ctx concern-а).
  * @param {typeof startChain} [deps.chainFactory] Фабрика ланцюжка (інжект для тестів).
+ * @param {typeof import('./test-gate.mjs').runTestFile} [deps.testRunner] Override
+ *   test-runner-а для test-gate (інжект для тестів цього модуля).
  * @returns {Promise<boolean>} Чи закрито concern (усі порушення усунено).
  */
 export async function fixConcern(item, initialViolations, deps) {
@@ -520,7 +689,8 @@ async function fixConcernCore(item, initialViolations, deps, chain, chainExtra,
       log,
       progress,
       verbose,
-      chain
+      chain,
+      testRunner: deps.testRunner
     })
     if (rung.isAvg) deps.spendAvg(1)
     chainExtra.rungs.push({
@@ -635,7 +805,7 @@ async function materializeTailToMt(remaining, cwd, log) {
  * @param {(s: string) => void} [opts.log] Логер виводу.
  * @param {boolean} [opts.isTTY] Override TTY-режиму ProgressReporter (тести); типово isTTY stdout.
  * @param {(snap: object) => void} [opts.onProgress] Публікація знімків прогресу назовні (черга lint --full).
- * @param {object} [opts.deps] Інжекти для тестів: { ladder, workerFor, t0For, chainFactory }.
+ * @param {object} [opts.deps] Інжекти для тестів: { ladder, workerFor, t0For, chainFactory, testRunner }.
  * @returns {Promise<0|1|2>} Exit code: 0 — чисто, 1 — лишились порушення, 2 — DetectorError.
  */
 export async function runFixPipeline(opts) {
@@ -709,7 +879,8 @@ export async function runFixPipeline(opts) {
         },
         workerOverride: deps.workerFor ? deps.workerFor(item.entry) : undefined,
         t0Override: patternsByItem.get(item),
-        chainFactory: deps.chainFactory
+        chainFactory: deps.chainFactory,
+        testRunner: deps.testRunner
       })
 
     let worst = 0

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

@@ -34,6 +34,8 @@ const ABSENT = Symbol('absent')
  *   або зроблено durable-позначку
  * @property {() => string[]} modifiedExisting наявні на момент S1 файли, чий поточний
  *   вміст відрізняється від pre-image (вхід semantic-collateral veto; нові файли не входять)
+ * @property {(absPath: string) => string|null} preImageOf pre-image вмісту файлу на момент
+ *   S1, або null якщо файл не було записано чи він не існував (вхід in-file hunk-level veto)
  */
 
 /**
@@ -78,6 +80,10 @@ export function createSnapshot() {
           ([abs, pre]) => pre !== ABSENT && !durable.has(abs) && (!existsSync(abs) || readFileSync(abs, 'utf8') !== pre)
         )
         .map(([abs]) => abs)
+    },
+    preImageOf(absPath) {
+      const pre = preImages.get(absPath)
+      return pre === undefined || pre === ABSENT ? null : pre
     }
   }
 }

package/scripts/lib/lint-surface/test-gate.mjs

@@ -0,0 +1,87 @@
+/**
+ * Test-gate верифікація для non-T0 (LLM) fix-ladder rung-ів (spec addendum
+ * 2026-07-24, ladder-collateral-in-file).
+ *
+ * `collateral-veto.mjs` детектує колатеральні правки лише ПОЗА target-set (інші
+ * файли) — правки ВСЕРЕДИНІ вже-таргетованого файлу (напр. видалення навмисного,
+ * задокументованого workaround поряд із фіксованим порушенням) ним не покриваються,
+ * а canonical re-detect бачить лише той самий детектор/те саме порушення, тож теж
+ * не ловить. Test-gate — легша альтернатива hunk-level diff (доки не реалізовано):
+ * якщо rung торкнувся файлу з target-set, для якого існує сестринський тест-файл за
+ * конвенцією `<dir>/tests/<stem>.test.{mjs,js,ts}` (n-test.mdc), той тест
+ * виконується як частина verify. Провал тесту → veto (як і collateral), rollback.
+ *
+ * Fail-open за дизайном (як і collateral-veto): відсутній test-runner (`bunx`/vitest
+ * недоступні), таймаут чи інша інфраструктурна помилка — НЕ блокує rung. Мета —
+ * зловити семантичну регресію, а не стати новою точкою відмови ladder-а.
+ */
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { basename, dirname, join } from 'node:path'
+
+const TEST_SUFFIXES = ['.test.mjs', '.test.js', '.test.ts']
+const SOURCE_SUFFIXES = ['.mjs', '.js', '.ts', '.vue']
+
+/** Таймаут одного тест-файлу (fail-open — вважається "не зламано" при перевищенні). */
+const TEST_RUN_TIMEOUT_MS = 30_000
+
+/**
+ * Сестринські тест-файли за конвенцією `<dir>/tests/<stem>.test.*` (n-test.mdc,
+ * той самий шаблон, що й зворотний `inferSourcePath` у coverage-provider).
+ * @param {string} sourceAbsPath Абсолютний шлях вихідного файлу.
+ * @returns {string[]} Наявні на диску сестринські тест-файли (може бути порожньо).
+ */
+export function findSiblingTestFiles(sourceAbsPath) {
+  const base = basename(sourceAbsPath)
+  const suffix = SOURCE_SUFFIXES.find(s => base.endsWith(s))
+  if (!suffix) return []
+  const stem = base.slice(0, -suffix.length)
+  const testsDir = join(dirname(sourceAbsPath), 'tests')
+  return TEST_SUFFIXES.map(ext => join(testsDir, `${stem}${ext}`)).filter(existsSync)
+}
+
+/**
+ * Виконує один тест-файл через vitest. Fail-open на будь-яку інфраструктурну
+ * помилку (bunx/vitest відсутній, spawn error, таймаут) — повертає `passed: true`,
+ * щоб test-gate ніколи не блокував ladder через відсутність test-runner-а.
+ * @param {string} testAbsPath Абсолютний шлях тест-файлу.
+ * @param {string} cwd Робоча директорія запуску.
+ * @returns {{ passed: boolean, output: string }} Результат прогону.
+ */
+export function runTestFile(testAbsPath, cwd) {
+  let result
+  try {
+    result = spawnSync('bunx', ['vitest', 'run', '--reporter=verbose', testAbsPath], {
+      cwd,
+      encoding: 'utf8',
+      timeout: TEST_RUN_TIMEOUT_MS,
+      env: process.env
+    })
+  } catch {
+    return { passed: true, output: '' }
+  }
+  // result.error — spawn сам не зміг стартувати (ENOENT тощо); status===null — вбито
+  // за таймаутом. Обидва — інфраструктурна невдача, не сигнал про код; fail-open.
+  if (result.error || result.status === null) return { passed: true, output: '' }
+  return { passed: result.status === 0, output: `${result.stdout ?? ''}\n${result.stderr ?? ''}`.slice(-2000) }
+}
+
+/**
+ * Test-gate над файлами, зміненими rung-ом В МЕЖАХ target-set (не колатеральними,
+ * ті вже покриті collateral-veto): перший сестринський тест, що впав, зупиняє
+ * пошук — цього достатньо, щоб відхилити clean-вердикт rung-а.
+ * @param {{ files: string[], cwd: string, runTest?: typeof runTestFile }} args files —
+ *   абсолютні шляхи наявних файлів у target-set, змінених rung-ом; cwd — робоча
+ *   директорія запуску тестів; runTest — override test-runner-а (тести цього модуля).
+ * @returns {{ file: string, testFile: string, output: string } | null} Перший
+ *   зафіксований провал або null, якщо всі сестринські тести (за наявності) пройшли.
+ */
+export function findBrokenSiblingTests({ files, cwd, runTest = runTestFile }) {
+  for (const file of files) {
+    for (const testFile of findSiblingTestFiles(file)) {
+      const { passed, output } = runTest(testFile, cwd)
+      if (!passed) return { file, testFile, output }
+    }
+  }
+  return null
+}

package/scripts/skills-cli.mjs

@@ -5,15 +5,14 @@
  * Промпт збирає інструкцію скілу + контекст поточного CWD (`package.json`, `tsconfig.json`,
  * `.n-rules.json`) — далі stdout або виконання через один з раннерів: вбудований
  * pi-агент, чи зовнішній ACP-агент. `cursor`/`codex` — через `@7n/llm-lib/acp`
- * (napi-міст до `llm_cascade::acp`, без власного JSON-RPC у JS); deprecated
+ * (napi-міст до `llm_lib::acp`, без власного JSON-RPC у JS); deprecated
  * `claude` — окремий JS-шим (`./lib/acp-runner.mjs`), бо Rust-крейт його не моделює.
  *
- * `skill <runner> taze` — виняток із загального шляху "весь SKILL.md одним промптом":
- * делегує в `../skills/taze/js/orchestrate.mjs`, який детерміновано (без LLM) робить
- * бекап/масовий bump/diff/прибирання і лише по одному ОБМЕЖЕНОМУ виклику `<runner>`
- * на кожен major-пакет — замість одного величезного непрозорого ходу на весь монорепо
- * (той, single-shot, раніше зависав без діагностики; per-пакет виклики успадковують
- * власний timeout раннера, і падіння одного пакета не втрачає прогрес по інших).
+ * `skill <runner> taze|git-reconcile` — JS-оркестровані винятки із загального
+ * шляху "весь SKILL.md одним промптом". `taze` детерміновано робить
+ * backup/bump/diff/cleanup і викликає LLM лише для major-міграцій;
+ * `git-reconcile` детерміновано інвентаризує Git-граф, готує worktree/PR і
+ * викликає LLM лише для semantic triage та conflict resolution.
  *
  * Підтримувані формати:
  *   `npx \@7n/rules skill list`
@@ -36,11 +35,12 @@ import { readSkillMetaRaw, skillTier } from './lib/skill-meta.mjs'
 
 /** Виконавці скіла. `pi` — вбудований (рекомендований); `cursor`/`codex`/`claude` — зовнішні ACP-агенти (`claude` — deprecated). */
 const RUNNERS = new Set(['pi', 'cursor', 'codex', 'claude'])
+const JS_ORCHESTRATED_SKILLS = new Set(['taze', 'git-reconcile'])
 
 /**
  * Раннери, що йдуть через зовнішнього ACP-агента, і чи deprecated (друкує попередження
  * перед запуском). `cursor`/`codex` — napi-міст `@7n/llm-lib/acp`; `claude` — окремий
- * JS-шим `runAcpRunner` (Rust-крейт `llm_cascade::acp` `claude` не моделює).
+ * JS-шим `runAcpRunner` (Rust-крейт `llm_lib::acp` `claude` не моделює).
  */
 const ACP_RUNNERS = {
   claude: { deprecated: true },
@@ -173,7 +173,7 @@ async function runPiRunner(prompt, rawSkillName, skillsRoot, projectDir, logErro
 
 /**
  * Делегує виконання скіла зовнішньому ACP-агенту. `cursor`/`codex` — через
- * `@7n/llm-lib/acp` (napi-міст до `llm_cascade::acp`: спавн, `session/prompt`,
+ * `@7n/llm-lib/acp` (napi-міст до `llm_lib::acp`: спавн, `session/prompt`,
  * автоапрув дозволів — усе в Rust, без JSON-RPC у JS). `claude` — deprecated
  * JS-шим `runAcpRunner` (Rust його не моделює); буде прибрано (мігруй на `skill pi`).
  * На відміну від колишнього стрімінгу по чанках, napi-шлях повертає повний текст
@@ -235,6 +235,33 @@ async function runTazeOrchestratorCli(runner, projectDir, log, logError, deps =
   }
 }
 
+/**
+ * Виконує `git-reconcile` через JS-оркестратор: Git inventory/patch-equivalence/
+ * worktree/cherry-pick/gates/push/PR — детерміновано; LLM — лише semantic triage
+ * та conflict resolution.
+ * @param {'pi' | 'cursor' | 'codex'} runner LLM-раннер для bounded кроків
+ * @param {string} projectDir корінь проєкту
+ * @param {string} task додатковий намір користувача
+ * @param {(line: string) => void} log прогрес/звіт
+ * @param {(line: string) => void} logError помилки
+ * @param {{ runGitReconcileOrchestrator?: (opts: object) => Promise<{ok:boolean,report:string}> }} [deps] інжекти
+ * @returns {Promise<number>} exit code
+ */
+async function runGitReconcileOrchestratorCli(runner, projectDir, task, log, logError, deps = {}) {
+  let orchestrate = deps.runGitReconcileOrchestrator
+  if (!orchestrate) {
+    const module = await import('../skills/git-reconcile/js/orchestrate.mjs')
+    orchestrate = module.runGitReconcileOrchestrator
+  }
+  try {
+    const result = await orchestrate({ cwd: projectDir, runner, task, log, deps })
+    return result.ok ? 0 : 1
+  } catch (error) {
+    logError(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}
+
 /**
  * Корінь пакета `@7n/rules` (каталог з `skills/`, `rules/`, …).
  * @param {string} [fromModuleUrl] для тестів — `import.meta.url`, відносно якого шукати корінь
@@ -261,6 +288,18 @@ export function isTazeOrchestratorSkillArgs(argv) {
   return RUNNERS.has(first) && first !== 'claude' && normalizeSkillId(second) === 'taze'
 }
 
+/**
+ * Чи аргументи ведуть у будь-який JS-оркестрований skill. Потрібно верхньому
+ * CLI, щоб не мутувати root package.json self-upgrade-ом до власного preflight
+ * оркестратора.
+ * @param {string[]} argv аргументи після `skill`
+ * @returns {boolean} true для taze/git-reconcile з pi/cursor/codex
+ */
+export function isJsOrchestratedSkillArgs(argv) {
+  const [first, second] = argv
+  return RUNNERS.has(first) && first !== 'claude' && JS_ORCHESTRATED_SKILLS.has(normalizeSkillId(second))
+}
+
 /**
  * @param {string[]} argv аргументи після `skill` у `n-rules`
  * @param {{ packageRoot?: string, projectDir?: string, log?: (line: string) => void, logError?: (line: string) => void, deps?: { runPiAgentSkill?: (prompt: string, opts?: object) => Promise<{ ok: boolean, error: string|null }> } }} [options] перевизначення кореня пакета, каталогу проєкту, функцій виводу та інжектів (для тестів)
@@ -295,7 +334,8 @@ export async function runSkillsCli(argv, options = {}) {
       if (!second) {
         throw new Error(`Skill name is required after "${first}"`)
       }
-      if (first !== 'claude' && normalizeSkillId(second) === 'taze') {
+      const skillId = normalizeSkillId(second)
+      if (first !== 'claude' && skillId === 'taze') {
         return await runTazeOrchestratorCli(
           /** @type {'pi' | 'cursor' | 'codex'} */ (first),
           projectDir,
@@ -304,6 +344,16 @@ export async function runSkillsCli(argv, options = {}) {
           deps
         )
       }
+      if (first !== 'claude' && skillId === 'git-reconcile') {
+        return await runGitReconcileOrchestratorCli(
+          /** @type {'pi' | 'cursor' | 'codex'} */ (first),
+          projectDir,
+          rest.join(' '),
+          log,
+          logError,
+          deps
+        )
+      }
       const task = rest.join(' ')
       const prompt = buildSkillPrompt(skillsRoot, second, task, projectDir)
       if (first === 'pi') {