@7n/rules 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.3.0] - 2026-07-14
+
+### Changed
+
+- doc-files: мʼякий дедлайн fix-pipeline тепер діє і всередині файлу — `generateDoc` ріже per-call LLM-таймаути під залишок бюджету рунга (`deadlineAt`), тож генерація, що не вкладається в рунг, обривається transient-помилкою сама, без батчу-зомбі поверх наступного rung-а і без «fix timeout» від backstop-таймера
+
+## [1.2.2] - 2026-07-14
+
+### Changed
+
+- release: @7n/llm-lib@2.6.1, @7n/rules@1.1.0
+
 ## [1.2.1] - 2026-07-14
 
 ### Fixed

package/package.json

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

package/rules/abie/clean_merged_ignore_branches/fix-clean_merged_ignore_branches.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'abie-clean_merged_ignore_branches-template', targetPath: '.github/workflows/clean-merged-branch.yml' })]

package/rules/doc-files/check/docs/fix-worker.md

@@ -3,7 +3,7 @@ type: JS Module
 title: fix-worker.mjs
 resource: npm/rules/doc-files/check/fix-worker.mjs
 docgen:
-  crc: 7611b2f9
+  crc: 27e4dca1
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -18,7 +18,7 @@ docgen:
 1. Викликається `fixWorker`.
 2. Скануються файли для визначення застарілих документів (рукописні доки без docgen-frontmatter — не цілі).
 3. Якщо знайдені застарілі документи, кожна цільова дока реєструється durable через `ctx.recordDurableWrite` (fallback — `ctx.recordWrite`), а потім запускається генерація батчу через `runGenerationBatch`.
-4. Батч отримує м'який дедлайн — 80% від `ctx.timeoutMs` рунга: генерація сама зупиняється до backstop-таймауту, повертає частковий прогрес штатно й не лишає фонового батчу поверх наступного rung-а.
+4. Батч отримує м'який дедлайн — 80% від `ctx.timeoutMs` рунга: генерація сама зупиняється до backstop-таймауту, повертає частковий прогрес штатно й не лишає фонового батчу поверх наступного rung-а. Дедлайн діє і всередині файлу: `generateDoc` ріже per-call LLM-таймаути під залишок бюджету, тож навіть перший файл, що не вкладається у рунг, обривається сам (transient), а не по backstop-таймеру runner-а.
 5. Фільтруються порушення, що стосуються сирітських документів (вихідні файли видалені); pre-image кожного реєструється у `ctx.recordWrite`.
 6. Викликається `purgeOrphanedDocs` для видалення сирітських документів.
 7. Повертається результат зі списком зачеплених файлів.

package/rules/doc-files/check/fix-worker.mjs

@@ -36,6 +36,8 @@ export async function fixWorker(violations, ctx) {
     }
     // Deadline: батч сам зупиняється до backstop-таймауту рунга (fix timeout ×1.25) —
     // повертає часткову роботу штатно, замість фонового батчу-зомбі поверх наступного rung-а.
+    // Дедлайн діє і всередині файлу: generateDoc ріже per-call LLM-таймаути під залишок
+    // бюджету, тож навіть перший файл, що не вкладається у рунг, обривається сам.
     const deadlineAt = ctx.timeoutMs ? Date.now() + Math.round(ctx.timeoutMs * DEADLINE_FRACTION) : null
     await runGenerationBatch(stale, cwd, {
       headline: `📄 doc-files: генерація ${stale.length} доки(ів)`,

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

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-files-batch/main.mjs
 docgen:
-  crc: 6237a73f
+  crc: 8b00ffa9
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.99
@@ -20,7 +20,7 @@ docgen:
 selectTargets вибирає файли для генерації документації, які є застарілими або мають низьку якість, виключаючи ті, що вже мають потік (tier) `cloud-avg`. Рукописні доки (docPath існує без docgen-frontmatter, `foreign`) без `--overwrite` цілями не стають.
 purgeOrphanedDocs видаляє вказівники на файли документації, для яких не існує відповідного вихідного файлу, і оновлює індекси директорій.
 runDocFilesGenCli керує процесом генерації документації, видаляючи сирітських доків, визначаючи цілі та запускаючи пакетну генерацію; про пропущені рукописні (foreign) доки попереджає у stderr — тихого перезапису людського змісту немає, перезапис лише explicit `--overwrite`.
-runGenerationBatch виконує генерацію документації для визначеного набору файлів, керуючи логікою циркут-брейкера при системних збоях; опційний `deadlineAt` (м'який дедлайн fix-pipeline) зупиняє батч перед стартом наступного файлу штатно — зроблене лишається на диску зі свіжими CRC, решту підбирає наступний прогін (перший файл стартує завжди).
+runGenerationBatch виконує генерацію документації для визначеного набору файлів, керуючи логікою циркут-брейкера при системних збоях; опційний `deadlineAt` (м'який дедлайн fix-pipeline) зупиняє батч перед стартом наступного файлу штатно — зроблене лишається на диску зі свіжими CRC, решту підбирає наступний прогін (перший файл стартує завжди). Той самий `deadlineAt` прокидається у `generateDoc`, тож per-call LLM-таймаути ріжуться під залишок бюджету і файл у процесі обривається на дедлайні transient-помилкою, а не живе батчем-зомбі поверх наступного rung-а.
 generateDirIndex (пере)генерує `index.md` директорії docs/ як OKF Directory Index без H1 у тілі — top-level заголовком лишається frontmatter `title:`, тож MD025/single-title чистий; чужий `index.md` (дока source-файлу чи людський зміст без OKF-типу) не перезаписується.
 runDocFilesStampCli оновлює метадані (frontmatter) наявних файлів документації, додаючи хеш вихідного файлу, без повторного запуску генерації.
 

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

@@ -145,10 +145,10 @@ function fmtSize(bytes) {
  * @param {string} root абсолютний корінь
  * @param {{ done: number, total: number }} progress позиція у прогресі
  * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор
- * @param {{ model?: string, tier?: string|null, emit?: (s: string) => void }} [opts] модель/тир для штампу; emit — логер рядка результату
+ * @param {{ model?: string, tier?: string|null, emit?: (s: string) => void, deadlineAt?: number|null }} [opts] модель/тир для штампу; emit — логер рядка результату; deadlineAt — мʼякий дедлайн fix-pipeline для generateDoc
  * @returns {Promise<'ok'|'permanent'|'systemic'|'transient'>} результат для керування циклом
  */
-async function generateOne(file, root, progress, stats, { model, tier, emit } = {}) {
+async function generateOne(file, root, progress, stats, { model, tier, emit, deadlineAt = null } = {}) {
   const out = emit ?? (s => process.stdout.write(s))
   const sourceAbs = join(root, file.sourcePath)
   let size = 0
@@ -162,7 +162,7 @@ async function generateOne(file, root, progress, stats, { model, tier, emit } =
     const docAbs = join(root, file.docPath)
     // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
     const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
-    const result = await generateDoc(sourceAbs, { existingMd, model })
+    const result = await generateDoc(sourceAbs, { existingMd, model, deadlineAt })
     const crc = crc32(readFileSync(sourceAbs))
     mkdirSync(dirname(docAbs), { recursive: true })
     const quality =
@@ -395,8 +395,11 @@ export function runDocFilesGenCli(argv) {
  *
  * `deadlineAt` (epoch ms): м'який дедлайн fix-pipeline — перед стартом КОЖНОГО
  * наступного файлу (перший стартує завжди) батч звіряється з дедлайном і, коли час
- * вийшов, завершується штатно з частковим прогресом. Зроблене записано по одному
- * файлу (durable, свіжий CRC) — наступний прогін підбирає решту за CRC.
+ * вийшов, завершується штатно з частковим прогресом. Той самий дедлайн прокидається
+ * у generateDoc: per-call LLM-таймаути ріжуться під залишок бюджету, тож і файл
+ * У ПРОЦЕСІ обривається на дедлайні (transient-помилка), а не живе батчем-зомбі
+ * поверх наступного rung-а. Зроблене записано по одному файлу (durable, свіжий
+ * CRC) — наступний прогін підбирає решту за CRC.
  * @param {Array<object>} targets елементи scanForDocFiles (sourcePath/docPath)
  * @param {string} root абсолютний корінь
  * @param {{ headline?: string, model?: string, tier?: string, deadlineAt?: number|null }} [opts] headline — рядок-шапка прогону у stdout; model/tier — override моделі і її типу (інакше DEFAULT_LOCAL_MODEL); deadlineAt — м'який дедлайн (epoch ms)
@@ -442,7 +445,8 @@ export async function runGenerationBatch(targets, root, opts = {}) {
       const status = await generateOne(file, root, { done, total: targets.length }, stats, {
         model: opts.model,
         tier: opts.tier,
-        emit
+        emit,
+        deadlineAt: opts.deadlineAt ?? null
       })
       reporter?.concernDone(file.sourcePath)
       // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,

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: bef08f19
+  crc: 344e711f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
@@ -26,6 +26,7 @@ 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
 
@@ -33,7 +34,8 @@ splitProtected — витягує тіло захищеної секції «П
 insertProtected — повертає захищений блок у фіксовану позицію одразу після заголовка документа.
 scoreDoc — детермінований скоринг документа (0 токенів) проти факт-листа: оцінка 0–100 і коди проблем.
 DEFAULT_LOCAL_MODEL — модель генерації за замовчуванням (env-конфігурована; без неї preflight фейлить гучно).
-generateDoc — головний вхід: джерело → md-дока з оцінкою якості, best-of-2 повтором і опційним семантичним суддею.
+generateDoc — головний вхід: джерело → md-дока з оцінкою якості, best-of-2 повтором і опційним семантичним суддею; опційний `deadlineAt` обмежує генерацію бюджетом рунга fix-pipeline.
+capTimeoutToDeadline — ріже базовий per-call таймаут під залишок до дедлайну (без дедлайну — базовий ліміт; після дедлайну — 0).
 
 ## Гарантії поведінки
 

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

@@ -30,22 +30,50 @@ let llmMeter = { calls: 0, ms: 0 }
  */
 let activeChain = null
 
+/**
+ * Дедлайн поточної генерації (epoch ms) — той самий lifecycle, що й activeChain:
+ * виставляється на старті generateDoc (opts.deadlineAt від fix-pipeline), скидається
+ * у finally. Ріже per-call таймаути так, що жоден LLM-виклик не переживає бюджет
+ * рунга — інакше backstop runner-а вбиває worker, а батч-зомбі продовжує дзвонити
+ * в локальну модель поверх наступного rung-а.
+ */
+let activeDeadlineAt = null
+
+/**
+ * Ріже базовий per-call таймаут під залишок бюджету до дедлайну.
+ * Без дедлайну — базовий ліміт; після дедлайну — 0 (виклик не має стартувати).
+ * @param {number} baseMs базовий ліміт виклику
+ * @param {number|null} deadlineAt дедлайн (epoch ms) або null
+ * @param {number} [now] поточний час (інжект для тестів)
+ * @returns {number} ефективний ліміт у мс (0 — бюджет вичерпано)
+ */
+export function capTimeoutToDeadline(baseMs, deadlineAt, now = Date.now()) {
+  if (!deadlineAt) return baseMs
+  return Math.min(baseMs, Math.max(0, deadlineAt - now))
+}
+
 /**
  * Обгортка LLM-виклику з обліком (тепер async поверх pi-one-shot): лічить кількість
  * викликів і сумарний час. Генерація одного файлу послідовна — лічильник без гонок.
  * Зберігає старий інтерфейс accountant'а: повертає рядок-вміст, кидає на помилці.
+ * Таймаут виклику ріжеться під activeDeadlineAt; вичерпаний бюджет — помилка зі
+ * словом «timeout» (класифікується transient у batch, не permanent/systemic).
  * @param {Array<{role:string,content:string}>} messages чат-повідомлення
  * @param {string} model model-id (`provider/id`)
  * @param {{ timeoutMs?: number, caller?: string }} [opts] ліміт/мітка (temperature/maxTokens не підтримуються pi-one-shot)
  * @returns {Promise<string>} відповідь моделі
  */
 async function callLlm(messages, model, opts = {}) {
+  const timeoutMs = capTimeoutToDeadline(opts.timeoutMs ?? LOCAL_TIMEOUT_MS, activeDeadlineAt)
+  if (timeoutMs <= 0) {
+    throw new Error('docgen deadline: бюджет рунга fix-pipeline вичерпано до старту LLM-виклику (timeout)')
+  }
   const started = Date.now()
   try {
     const res = await runOneShot({
       messages,
       modelSpec: model,
-      timeoutMs: opts.timeoutMs,
+      timeoutMs,
       caller: opts.caller ?? 'docgen',
       chain: activeChain
     })
@@ -453,12 +481,18 @@ function finishUnsupported(r, { t0, model, chainExtra }) {
  * з вищою температурою (best-of-2); якщо й він не допоміг — результат
  * позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
  * @param {string} file абсолютний шлях джерела
- * @param {{ model?: string, threshold?: number, existingMd?: string|null, chainFactory?: typeof startChain }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції), фабрика ланцюжка (інжект для тестів)
+ * @param {{ model?: string, threshold?: number, existingMd?: string|null, chainFactory?: typeof startChain, deadlineAt?: number|null }} [opts] model-id, поріг degraded, наявна дока (для збереження захищеної секції), фабрика ланцюжка (інжект для тестів), deadlineAt — мʼякий дедлайн fix-pipeline (epoch ms): per-call таймаути ріжуться під залишок бюджету, вичерпаний бюджет обриває генерацію transient-помилкою
  * @returns {{ md: string, ms: number, llmMs: number, llmCalls: number, score: number|null, issues: string[], degraded: boolean, model: string }} документ і метадані генерації (ms — увесь файл; llmMs/llmCalls — лише LLM; решта ms — оркестрація)
  */
 export async function generateDoc(
   file,
-  { model = DEFAULT_LOCAL_MODEL, threshold = QUALITY_THRESHOLD, existingMd = null, chainFactory = startChain } = {}
+  {
+    model = DEFAULT_LOCAL_MODEL,
+    threshold = QUALITY_THRESHOLD,
+    existingMd = null,
+    chainFactory = startChain,
+    deadlineAt = null
+  } = {}
 ) {
   const src = readFileSync(file, 'utf8')
   // Pre-send guard: весь src вшивається у промпт як є (екстракт фактів його НЕ
@@ -477,6 +511,7 @@ export async function generateDoc(
   llmMeter = { calls: 0, ms: 0 }
   const chain = chainFactory({ kind: 'doc-generate', unit: facts.relPath, cwd: process.cwd() })
   activeChain = chain
+  activeDeadlineAt = deadlineAt
   const chainExtra = {}
   try {
     return await generateDocCore()
@@ -485,6 +520,7 @@ export async function generateDoc(
     throw error
   } finally {
     activeChain = null
+    activeDeadlineAt = null
     let outcome = 'success'
     if (chainExtra.error) outcome = 'fail'
     else if (chainExtra.degraded) outcome = 'partial'

package/rules/docker/lint_docker_yml/fix-lint_docker_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'docker-lint_docker_yml-template', targetPath: '.github/workflows/lint-docker.yml' })]

package/rules/ga/clean_ga_workflows/fix-clean_ga_workflows.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-clean_ga_workflows-template', targetPath: '.github/workflows/clean-ga-workflows.yml' })]

package/rules/ga/clean_merged_branch/fix-clean_merged_branch.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-clean_merged_branch-template', targetPath: '.github/workflows/clean-merged-branch.yml' })]

package/rules/ga/git_ai/fix-git_ai.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-git_ai-template', targetPath: '.github/workflows/git-ai.yml' })]

package/rules/ga/lint_ga/fix-lint_ga.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-lint_ga-template', targetPath: '.github/workflows/lint-ga.yml' })]

package/rules/ga/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/ga/zizmor_yml/fix-zizmor_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'ga-zizmor_yml-template', targetPath: '.github/zizmor.yml' })]

package/rules/js/jscpd_config/fix-jscpd_config.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'js-jscpd_config-template', targetPath: '.jscpd.json' })]

package/rules/js/lint_js_yml/fix-lint_js_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'js-lint_js_yml-template', targetPath: '.github/workflows/lint-js.yml' })
+]

package/rules/js/package_json/fix-package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'js-package_json-template', targetPath: 'package.json' })]

package/rules/k8s/lint_k8s_yml/fix-lint_k8s_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'k8s-lint_k8s_yml-template', targetPath: '.github/workflows/lint-k8s.yml' })]

package/rules/npm-module/emit_types_config/fix-emit_types_config.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-emit_types_config-template', targetPath: 'npm/tsconfig.emit-types.json' })]

package/rules/npm-module/npm_package_json/fix-npm_package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-npm_package_json-template', targetPath: 'npm/package.json' })]

package/rules/npm-module/npm_publish_yml/fix-npm_publish_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'npm-module-npm_publish_yml-template', targetPath: '.github/workflows/npm-publish.yml' })
+]

package/rules/npm-module/root_package_json/fix-root_package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'npm-module-root_package_json-template', targetPath: 'package.json' })]

package/rules/php/lint_php_yml/fix-lint_php_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'php-lint_php_yml-template', targetPath: '.github/workflows/lint-php.yml' })]

package/rules/python/lint_python_yml/fix-lint_python_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'python-lint_python_yml-template', targetPath: '.github/workflows/lint-python.yml' })]

package/rules/rego/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'rego-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/rust/lint_rust_yml/fix-lint_rust_yml.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'rust-lint_rust_yml-template', targetPath: '.github/workflows/lint-rust.yml' })
+]

package/rules/security/lint_security_yml/fix-lint_security_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'security-lint_security_yml-template', targetPath: '.github/workflows/lint-security.yml' })]

package/rules/style/lint_style_yml/fix-lint_style_yml.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-lint_style_yml-template', targetPath: '.github/workflows/lint-style.yml' })]

package/rules/style/package_json/fix-package_json.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-package_json-template', targetPath: 'package.json' })]

package/rules/style/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'style-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/text/lint_text/fix-lint_text.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'text-lint_text-template', targetPath: '.github/workflows/lint-text.yml' })
+]

package/rules/text/oxfmtrc/fix-oxfmtrc.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'text-oxfmtrc-template', targetPath: '.oxfmtrc.json' })]

package/rules/text/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'text-vscode_settings-template', targetPath: '.vscode/settings.json' })]

package/rules/worktree/vscode_settings/fix-vscode_settings.mjs

@@ -0,0 +1,5 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [
+  createTemplateFixPattern({ id: 'worktree-vscode_settings-template', targetPath: '.vscode/settings.json' })
+]

package/rules/worktree/zed_settings/fix-zed_settings.mjs

@@ -0,0 +1,3 @@
+import { createTemplateFixPattern } from '../../../scripts/lib/fix/template-deep-merge.mjs'
+
+export const patterns = [createTemplateFixPattern({ id: 'worktree-zed_settings-template', targetPath: '.zed/settings.json' })]

package/scripts/lib/fix/template-deep-merge.mjs

@@ -0,0 +1,182 @@
+/**
+ * Спільний T0-autofix writer для policy-концернів "один target-файл + один канонічний
+ * `template/*.snippet.{json,jsonc,yml,yaml}`" (`engine:"template"` і `engine:"rego"`
+ * з тим самим snippet-шаблоном). Deep-merge snippet → target: об'єкти мерджаться по
+ * ключах, масиви — union за структурним підмножинним збігом (`checkSnippet`-семантика,
+ * як у детекторі — жодного окремого визначення "збігу"), листя — перезаписується
+ * канонічним значенням. Файл відсутній → копіюється сам snippet (без merge).
+ *
+ * JSON/JSONC — plain-object merge + `JSON.stringify`. YAML — `yaml` Document API
+ * (`setIn`/`addIn`/`hasIn`), щоб зберегти коментарі й форматування наявного файлу;
+ * створюється лише те, чого бракує.
+ *
+ * Кожен викличний concern передає лише `{ id, targetPath }` — сам writer резолвить
+ * snippet-файл у `template/` свого concern-а через `ctx.concernDir` (той самий
+ * механізм, що й `vscode-ext-add.mjs`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { basename, dirname, extname, join } from 'node:path'
+
+import { checkSnippet } from '../template.mjs'
+
+const SNIPPET_EXTS = ['yml', 'yaml', 'json', 'jsonc']
+
+/**
+ * Чи `needle` структурно вже присутній у якомусь елементі `actualArray`
+ * (та сама subset-семантика, що й у детекторі — жодного окремого визначення "збігу").
+ * @param {unknown[]} actualArray наявний масив
+ * @param {unknown} needle елемент снippета, наявність якого перевіряємо
+ * @returns {boolean} true — вже присутній структурно
+ */
+function containedIn(actualArray, needle) {
+  return actualArray.some(a => checkSnippet(a, needle, { targetPath: '', source: '' }).length === 0)
+}
+
+/**
+ * Шукає `<basename>.snippet.<ext>` у `template/` concern-а (перебір відомих розширень).
+ * @param {string} templateDir абсолютний шлях до `template/` concern-а
+ * @param {string} targetBasename basename цільового файлу (напр. `npm-publish.yml`)
+ * @returns {string|null} абсолютний шлях до snippet-файлу або null
+ */
+function findSnippetFile(templateDir, targetBasename) {
+  if (!existsSync(templateDir)) return null
+  for (const ext of SNIPPET_EXTS) {
+    const p = join(templateDir, `${targetBasename}.snippet.${ext}`)
+    if (existsSync(p)) return p
+  }
+  return null
+}
+
+/**
+ * Рекурсивний deep-merge snippet у plain JS-значення (JSON/JSONC-гілка).
+ * @param {unknown} actual наявне значення (або undefined)
+ * @param {unknown} snippet канонічний фрагмент
+ * @returns {unknown} злите значення
+ */
+function mergeJsonValue(actual, snippet) {
+  if (Array.isArray(snippet)) {
+    const arr = Array.isArray(actual) ? [...actual] : []
+    for (const needle of snippet) {
+      if (!containedIn(arr, needle)) arr.push(needle)
+    }
+    return arr
+  }
+  if (snippet !== null && typeof snippet === 'object') {
+    const obj = actual !== null && typeof actual === 'object' && !Array.isArray(actual) ? { ...actual } : {}
+    for (const [k, v] of Object.entries(snippet)) obj[k] = mergeJsonValue(obj[k], v)
+    return obj
+  }
+  return snippet // leaf — перезаписуємо канонічним значенням
+}
+
+/**
+ * Deep-merge snippet у YAML `Document` за шляхом (мутує `doc`). Масиви — `addIn` лише
+ * відсутніх (структурно) елементів; об'єкти — рекурсія по ключах (`setIn` створює
+ * проміжні мапи автоматично); листя — `setIn`.
+ * @param {import('yaml').Document} doc YAML-документ (мутується)
+ * @param {unknown} snippet канонічний фрагмент на цьому шляху
+ * @param {Array<string|number>} path шлях у документі
+ * @returns {void}
+ */
+function mergeYamlDoc(doc, snippet, path) {
+  if (Array.isArray(snippet)) {
+    // `doc.createNode([])` — примусово YAMLSeq-вузол; голий `setIn(path, [])` іноді
+    // лишає сирий JS-масив (коли батьківська мапа вже існує), і подальший `addIn` кидає
+    // `Expected YAML collection at …` — createNode гарантує коректний тип вузла завжди.
+    if (!doc.hasIn(path)) doc.setIn(path, doc.createNode([]))
+    const existing = doc.getIn(path)
+    const existingJs = existing && typeof existing.toJS === 'function' ? existing.toJS(doc) : []
+    for (const needle of snippet) {
+      if (!containedIn(existingJs, needle)) doc.addIn(path, needle)
+    }
+    return
+  }
+  if (snippet !== null && typeof snippet === 'object') {
+    for (const [k, v] of Object.entries(snippet)) mergeYamlDoc(doc, v, [...path, k])
+    return
+  }
+  doc.setIn(path, snippet) // leaf — перезаписуємо канонічним значенням
+}
+
+/**
+ * Створює T0-патерн, що приводить `targetPath` у відповідність `template/*.snippet.*`
+ * свого concern-а (deep-merge, idempotent). Один writer — для будь-якого single-target
+ * snippet-концерну (`engine:"template"` чи `engine:"rego"` з тим самим snippet-шаблоном).
+ * @param {{ id: string, targetPath: string }} opts `id` — унікальний id T0-патерну; `targetPath` — posix-relative шлях цільового файлу від cwd
+ * @returns {import('../lint-surface/types.mjs').T0Pattern} T0-патерн для `fix-<concern>.mjs`
+ */
+export function createTemplateFixPattern({ id, targetPath }) {
+  return {
+    id,
+    test: violations => violations.some(v => v.file === targetPath),
+    apply: async (violations, ctx) => {
+      if (!violations.some(v => v.file === targetPath)) return { touchedFiles: [] }
+      if (!ctx.concernDir) return { touchedFiles: [] }
+
+      const snippetPath = findSnippetFile(join(ctx.concernDir, 'template'), basename(targetPath))
+      if (!snippetPath) return { touchedFiles: [] }
+
+      const absTarget = join(ctx.cwd, targetPath)
+      const ext = extname(snippetPath).toLowerCase()
+      const isJson = ext === '.json' || ext === '.jsonc'
+
+      const prevText = existsSync(absTarget) ? readFileSync(absTarget, 'utf8') : null
+
+      // Файл відсутній → копіюємо snippet як є (без merge — немає з чим мерджити).
+      if (prevText === null) {
+        const rawSnippet = readFileSync(snippetPath, 'utf8')
+        ctx.recordWrite?.(absTarget)
+        mkdirSync(dirname(absTarget), { recursive: true })
+        writeFileSync(absTarget, rawSnippet, 'utf8')
+        return { touchedFiles: [absTarget], message: `${targetPath}: створено зі snippet` }
+      }
+
+      let nextText
+      if (isJson) {
+        let snippet
+        let actual
+        try {
+          snippet = JSON.parse(readFileSync(snippetPath, 'utf8'))
+          actual = JSON.parse(prevText)
+        } catch {
+          return { touchedFiles: [] } // невалідний JSON — не чіпаємо детермінованим фіксом
+        }
+        // Уже відповідає snippet-у (та сама перевірка, що й детектор) → не чіпаємо файл
+        // взагалі: без цієї гейтки JSON.stringify переформатував би вже коректний файл
+        // (напр. компактний однорядковий snippet → pretty-print) без жодної реальної зміни.
+        if (checkSnippet(actual, snippet, { targetPath: '', source: '' }).length === 0) {
+          return { touchedFiles: [] }
+        }
+        const merged = mergeJsonValue(actual, snippet)
+        nextText = JSON.stringify(merged, null, 2) + '\n'
+      } else {
+        const { parse, parseDocument } = await import('yaml')
+        let snippet
+        let actualPlain
+        try {
+          snippet = parse(readFileSync(snippetPath, 'utf8'))
+          actualPlain = parse(prevText)
+        } catch {
+          return { touchedFiles: [] } // невалідний YAML — не чіпаємо детермінованим фіксом
+        }
+        // Уже відповідає snippet-у (та сама перевірка, що й детектор) → не чіпаємо файл
+        // взагалі: Document.toString() не завжди byte-identical на вже коректному вмісті
+        // (напр. folded block scalars переформатовуються при round-trip без потреби).
+        if (checkSnippet(actualPlain, snippet, { targetPath: '', source: '' }).length === 0) {
+          return { touchedFiles: [] }
+        }
+        const doc = parseDocument(prevText)
+        if (doc.errors.length > 0) return { touchedFiles: [] }
+        if (snippet !== null && typeof snippet === 'object' && !Array.isArray(snippet)) {
+          for (const [k, v] of Object.entries(snippet)) mergeYamlDoc(doc, v, [k])
+        }
+        nextText = doc.toString()
+      }
+
+      if (nextText === prevText) return { touchedFiles: [] }
+      ctx.recordWrite?.(absTarget)
+      writeFileSync(absTarget, nextText, 'utf8')
+      return { touchedFiles: [absTarget], message: `${targetPath}: приведено у відповідність snippet` }
+    }
+  }
+}