@7n/rules 1.39.0 → 1.40.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.40.1] - 2026-07-22
+
+### Fixed
+
+- `lint --full`: загублений `await` перед `ensureRunningInWorktree` ламав кожен прогін (у т.ч. зсередини `.worktrees/`) з `TypeError [ERR_INVALID_ARG_TYPE]`; заодно — guard проти видалення auto-created worktree при частковому провалі перенесення змін назад, і stack trace для programmer-помилок у top-level catch
+
+## [1.40.0] - 2026-07-22
+
+### Changed
+
+- doc-files: пакет покращень генерації на малих локальних моделях (gemma-4, живий бенч на efes/backend) — R9 дет-зрізання чат-преамбул + штраф скорера; Behavior-наратив замість дубля «Публічного API»; STYLE-заборони мета-фраз; анкор лише в Behavior-промпті (без дублю в Огляді); scoped read-only гарантія (без over-claim, який валив LLM-суддя); юніт-дайджест замість сирого src для великих файлів (`N_CURSOR_DOCGEN_DIGEST_TOKENS`); judge-refine — один локальний фікс за зауваженнями судді з guard-ами (`N_CURSOR_DOCGEN_JUDGE_REFINE=0` — опт-аут)
+
 ## [1.39.0] - 2026-07-21
 
 ### Added

package/bin/n-rules.js

@@ -1848,7 +1848,7 @@ try {
         // дереві задачі, worktree-ізоляція зламала б саму суть дельти) — пропускаємо.
         const needsWorktreeIsolation = full && !noFix
         const worktree = needsWorktreeIsolation
-          ? ensureRunningInWorktree(cwdArg, spawnSync, line => console.log(line), {
+          ? await ensureRunningInWorktree(cwdArg, spawnSync, line => console.log(line), {
               suffix: 'lint',
               description: 'n-rules lint --full: worktree-only full-repo run'
             })
@@ -1881,14 +1881,26 @@ try {
         } finally {
           // Лише для АВТОстворених worktree (лінт уже сидів у своєму — не наш, не чіпаємо).
           if (worktree.autoCreated) {
+            let bringBackFailed = true
             try {
-              await bringChangesBackToOriginal(runCwd, cwdArg, spawnSync, line => console.log(line))
+              const bringBackResult = await bringChangesBackToOriginal(runCwd, cwdArg, spawnSync, line =>
+                console.log(line)
+              )
+              bringBackFailed = bringBackResult.failed
             } catch (error) {
               console.log(
                 `⚠️ Перенесення змін назад провалилось: ${error instanceof Error ? error.message : String(error)}`
               )
             }
-            removeAutoCreatedWorktree(worktree.branchArg, cwdArg, spawnSync, line => console.log(line))
+            // Прибираємо worktree лише якщо перенесення точно вдалось — інакше
+            // не перенесені зміни згорять разом з деревом.
+            if (bringBackFailed) {
+              console.log(
+                `⚠️ Перенесення назад не підтверджено — worktree "${worktree.branchArg}" лишається для ручного розбору.`
+              )
+            } else {
+              removeAutoCreatedWorktree(worktree.branchArg, cwdArg, spawnSync, line => console.log(line))
+            }
           }
         }
 
@@ -1964,8 +1976,15 @@ try {
     }
   }
 } catch (error) {
+  // TypeError/RangeError/ReferenceError сигналять баг у самому коді (не навмисне
+  // user-facing повідомлення) — друкуємо stack одразу, інакше діагностика вимагає
+  // патчити node_modules вручну (як під час діагностики цього ж класу вад).
+  const isProgrammerError = error instanceof TypeError || error instanceof RangeError || error instanceof ReferenceError
   if (error instanceof ReexecHandoff) {
     process.exitCode = error.code
+  } else if (isProgrammerError && error.stack) {
+    console.error(error.stack)
+    process.exitCode = 1
   } else if (error instanceof Error && error.message) {
     console.error(error.message)
     process.exitCode = 1

package/package.json

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

package/rules/doc-files/docgen-extract-anchors/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-extract-anchors/main.mjs
 docgen:
-  crc: 1bd4d187
+  crc: 0d5bc487
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 95
   issues: anchor-miss:(rule.mdc),judge:inaccurate:0.99

package/rules/doc-files/docgen-extract-anchors/main.mjs

@@ -111,5 +111,8 @@ export function anchorsToPrompt(a) {
     blocks.push(`Приклади з документації автора (наведи дослівно у Поведінці):\n${fenced}`)
   }
   if (!blocks.length) return ''
-  return `АНКОРИ ДО ОБОВ'ЯЗКОВОГО ВКЛЮЧЕННЯ:\n${blocks.join('\n')}`
+  // «РІВНО один раз»: без цього gemma-подібні моделі «запихають» анкор у кожну
+  // секцію (живий кейс efes: URL https://hasura.io/jwt/claims і в Огляді, і в
+  // Поведінці, обидва рази незграбно). Скорер (R5) вимагає лише наявність.
+  return `АНКОРИ ДО ОБОВ'ЯЗКОВОГО ВКЛЮЧЕННЯ (кожен згадай РІВНО ОДИН раз, у найдоречнішому місці — не повторюй у кількох секціях):\n${blocks.join('\n')}`
 }

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: c9c9970b
+  crc: c02d3a1f
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 

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

@@ -20,7 +20,10 @@ import {
   guaranteesFromMarkers,
   isApiGap,
   renderApiLine,
-  apiGapMessages
+  apiGapMessages,
+  buildUnitDigest,
+  UNIT_DIGEST_TOKENS,
+  judgeRefineMessages
 } from '../docgen-prompts/main.mjs'
 
 /** Облік LLM-викликів і часу в них у межах однієї генерації (скидається на старті generateDoc). */
@@ -91,6 +94,23 @@ async function callLlm(messages, model, opts = {}) {
 const FENCE_OPEN_RE = /^```[a-z]*\n?/
 const FENCE_CLOSE_RE = /\n?```\s*$/
 const LEADING_HEADING_RE = /^#{1,6}[ \t]{1,8}[^\n]{0,400}\n{1,8}/
+// R9: чат-преамбули малих моделей — «озвучування завдання» перед відповіддю
+// («Ось оновлена чорнетка секції…», «Як технічний письменник, я створю…»,
+// «Оновлений текст секції:»). Живі приклади — прогін gemma-4 по efes/backend
+// 2026-07-21: 4 з 10 доків мали такі рядки; R8 (refusal) їх не ловить, бо далі
+// йде реальний контент. Зрізаються ЛИШЕ провідні рядки секції (мета-нарація
+// стоїть попереду), щоб не зачепити легітимний текст усередині.
+const PREAMBLE_LINE_RES = [
+  /^Ось (?:оновлен|переписан|виправлен|готов|вміст|текст|чорнетк|секці)/i,
+  /^Оновлен(?:ий|а|е|о) (?:текст|чорнетк|секці|вміст|версі)/i,
+  /^Як технічний письменник/i,
+  /^(?:Я )?(?:створю|напишу|перепишу|підготую) /i,
+  /^(?:Звісно|Гаразд|Добре)[,.!]/i,
+  /^(?:Нижче наведено|Нижче — )/i
+]
+// Дубль назви секції першим рядком тіла («Поведінка:» всередині секції Поведінка).
+// Рядок перед перевіркою вже пройшов trim (див. stripLeadingPreamble) — без \s*-країв.
+const SECTION_LABEL_LINE_RE = /^(?:Огляд|Поведінка|Публічний API|Гарантії поведінки):?$/
 const SECTION_HEADING_RE = /^##\s+(.+)/
 const SECTION_KEY_CLEAN_RE = /[^а-яіїєґa-z0-9]/gi
 const CACHE_MENTION_RE = /кеш/i
@@ -120,8 +140,26 @@ const H2_RE = /^##\s/
 const H1_RE = /^#\s/
 
 /**
- * Прибирає код-фенс-обгортку (потрійні бектіки) й випадковий провідний
- * `##`-заголовок із секції.
+ * R9: зрізає провідні чат-преамбули й дубль назви секції з початку тексту.
+ * Ітерується, поки перший непорожній рядок лишається мета-нарацією — модель
+ * інколи ставить дві поспіль («Як технічний письменник…» + «Ось оновлений…»).
+ * @param {string} t текст після базового очищення
+ * @returns {string} текст без провідних мета-рядків
+ */
+export function stripLeadingPreamble(t) {
+  let out = t
+  for (;;) {
+    const nl = out.indexOf('\n')
+    const first = (nl === -1 ? out : out.slice(0, nl)).trim()
+    const isMeta = SECTION_LABEL_LINE_RE.test(first) || PREAMBLE_LINE_RES.some(re => re.test(first))
+    if (!first || !isMeta || nl === -1) return isMeta && nl === -1 ? '' : out
+    out = out.slice(nl + 1).trimStart()
+  }
+}
+
+/**
+ * Прибирає код-фенс-обгортку (потрійні бектіки), випадковий провідний
+ * `##`-заголовок і чат-преамбули (R9) із секції.
  * @param {string} text сирий вихід моделі
  * @returns {string} очищений текст секції
  */
@@ -131,7 +169,7 @@ function stripSection(text) {
     t = t.replace(FENCE_OPEN_RE, '').replace(FENCE_CLOSE_RE, '').trim()
   }
   t = t.replace(LEADING_HEADING_RE, '') // зрізати випадковий заголовок
-  return t.trim()
+  return stripLeadingPreamble(t.trim()).trim()
 }
 
 /**
@@ -276,6 +314,19 @@ export function scoreDoc(md, facts, { anchors = null, src = '' } = {}) {
     issues.push('refusal-filler')
   }
 
+  // R9: чат-преамбула в тілі («Ось оновлена чорнетка…», «Як технічний письменник…»)
+  // — на відміну від R8, далі є реальний контент, тож не 0, а відчутний штраф:
+  // best-of-2 обере чистий драфт, а стійке сміття помітить degraded-доретрай.
+  // stripSection зрізає провідні мета-рядки на генерації; скорер — страховка для
+  // one-shot шляху і преамбул усередині секції (після першого рядка).
+  for (const line of splitProtected(md).without.split('\n')) {
+    if (PREAMBLE_LINE_RES.some(re => re.test(line.trim()))) {
+      score -= 25
+      issues.push('chat-preamble')
+      break
+    }
+  }
+
   if (!s['огляд']) {
     score -= 25
     issues.push('no-overview')
@@ -440,15 +491,103 @@ async function orchestratedDoc(
   // R3: «Огляд» — ОСТАННІМ, узагальненням уже написаної Поведінки (не голого факт-листа)
   let overview = stripSignatures(
     stripSection(
-      await callLlm(overviewMessages(facts, sections.behavior ?? '', anc, intent), model, { timeoutMs, temperature })
+      await callLlm(overviewMessages(facts, sections.behavior ?? '', intent), model, { timeoutMs, temperature })
     )
   )
-  overview = await critiqueRefineSection('overview', overview, facts, anc, model, timeoutMs)
+  // №8: анкори лише в Behavior — критик Огляду без анкор-блоку, інакше refine
+  // «поверне» анкор у Огляд і в документі він знову зʼявиться двічі.
+  overview = await critiqueRefineSection('overview', overview, facts, null, model, timeoutMs)
   sections.overview = overview
   // Варіант B: дослівно повертаємо захищений блок у фіксовану позицію
   return { md: insertProtected(assemble(basename(facts.relPath), sections), intent) }
 }
 
+/**
+ * №6 — judge-refine: суддя назвав конкретні неточності (`judge.reason`) — один
+ * локальний refine-прохід замість лише маркування degraded. Приймаємо виправлену
+ * версію ТІЛЬКИ якщо: det-score не впав, усі ## заголовки збережені, і повторний
+ * суддя більше не каже inaccurate. Інакше — оригінал і degraded, як раніше.
+ * Cap: рівно одна ітерація (без петель самопереконання).
+ * @param {{ md: string }} r поточний результат генерації
+ * @param {{ reason: string }} judge вердикт судді (inaccurate)
+ * @param {{ facts: object, anchors: object|null, src: string, score: number, model: string, chain: object }} ctx контекст генерації
+ * @returns {Promise<{ md: string, score: number, issues: string[], judge: object }|null>} прийнята виправлена версія або null (лишаємо оригінал)
+ */
+async function judgeRefinePass(r, judge, { facts, anchors, src, score, model, chain }) {
+  const { body: intentBody, without } = splitProtected(r.md)
+  const fixedRaw = await callLlm(judgeRefineMessages(without, judge.reason), model, { timeoutMs: LOCAL_TIMEOUT_MS })
+  let fixed = stripSection(fixedRaw)
+  if (!fixed.startsWith('#')) fixed = `# ${basename(facts.relPath)}\n\n${fixed}`
+  const fixedMd = insertProtected(fixed + '\n', intentBody)
+  // Guard 1: рерайт не має губити секції (малі моделі інколи повертають фрагмент)
+  const origHeadings = r.md.match(/^##\s.+$/gm) ?? []
+  if (origHeadings.some(h => !fixedMd.includes(h))) return null
+  // Guard 2: det-score не має падати
+  const sFixed = scoreDoc(fixedMd, facts, { anchors, src })
+  if (sFixed.score < score) return null
+  // Guard 3: повторний суддя (той самий scope: inaccurate)
+  const judge2 = { ...(await judgeDoc(src, fixedMd, { chain })), model: JUDGE_MODEL }
+  if (judgeFailsDoc(judge2)) return null
+  return { md: fixedMd, score: sFixed.score, issues: sFixed.issues, judge: judge2 }
+}
+
+/**
+ * Judge-гейт цілком (виклик судді + опційний №6 refine): обгортка для
+ * generateDocCore, щоб тримати його cognitive complexity в межах. Помилки судді
+ * не валять генерацію — лише issue-маркер, як і раніше.
+ * @param {{ r: {md: string}, score: number, issues: string[], facts: object, anchors: object|null, src: string, model: string, chain: object }} ctx стан генерації
+ * @returns {Promise<{ judge: object|null, r: {md: string}, score: number, issues: string[] }>} оновлений стан
+ */
+async function runJudgeGate({ r, score, issues, facts, anchors, src, model, chain }) {
+  let judge = null
+  try {
+    judge = { ...(await judgeDoc(src, r.md, { chain })), model: JUDGE_MODEL }
+    // №6: суддя назвав конкретні неточності → один локальний refine-прохід
+    // (опт-аут: N_CURSOR_DOCGEN_JUDGE_REFINE=0). Прийнято лише коли всі
+    // guard-и judgeRefinePass пройдені; інакше — degraded, як раніше.
+    if (judgeFailsDoc(judge) && env.N_CURSOR_DOCGEN_JUDGE_REFINE !== '0') {
+      const refined = await judgeRefinePass(r, judge, { facts, anchors, src, score, model, chain })
+      if (refined) {
+        r = { ...r, md: refined.md }
+        score = refined.score
+        issues = [...refined.issues, 'judge-refine:won']
+        judge = refined.judge
+      } else {
+        issues = [...issues, 'judge-refine:kept-original']
+      }
+    }
+    if (judgeFailsDoc(judge)) issues = [...issues, `judge:inaccurate:${judge.confidence}`]
+  } catch (error) {
+    issues = [...issues, `judge:error: ${error.message.slice(0, 80)}`]
+  }
+  return { judge, r, score, issues }
+}
+
+/**
+ * №5 (бенч gemma-4): текст «коду файлу» для Behavior-промпта. Великий src
+ * (понад UNIT_DIGEST_TOKENS) → юніт-дайджест (імʼя + JSDoc + call-graph + тіло
+ * лише для непокритих юнітів) замість сирого коду: на ~6k токенів сирцю мала
+ * модель втрачає фокус і пише водянисто. Анкори/CRC — завжди від повного src
+ * (дайджест лише для промпта). units нема (парсинг упав чи мова без юніт-шару)
+ * — повний src, як раніше.
+ * @param {{ facts: object, estTokens: number, langExtractors: Map<string, object>, ext: string, src: string, file: string }} ctx контекст генерації
+ * @returns {string} повний src або юніт-дайджест
+ */
+function resolvePromptSrc({ facts, estTokens, langExtractors, ext, src, file }) {
+  if (facts.unsupported || estTokens <= UNIT_DIGEST_TOKENS) return src
+  const units = langExtractors.get(ext)?.extractUnits?.(src, file)
+  if (!units?.length) return src
+  // Гейт змістовності (фінальний бенч, upsert-order 23KB): дайджест виграє лише
+  // коли файл СТРУКТУРОВАНИЙ (декілька юнітів — call-graph несе інформацію) і
+  // більшість юнітів покриті JSDoc. Інакше він вироджений: (а) юніти без JSDoc →
+  // обрізані тіла без описів → Поведінка стискається до generic (246 знаків
+  // проти 1300+ на повному src, score 65); (б) один гігантський юніт → дайджест
+  // = один рядок JSDoc, вся логіка невидима. В обох випадках — повний src.
+  const covered = units.filter(u => u.doc).length
+  const structured = units.length >= 4 && covered / units.length >= 0.6
+  return structured ? buildUnitDigest(units) : src
+}
+
 /** Максимальний час генерації одного LLM-виклику. */
 const LOCAL_TIMEOUT_MS = 5 * 60 * 1000
 
@@ -569,9 +708,10 @@ export async function generateDoc(
     // Варіант B: захищена секція «Призначення» з наявної доки — зберегти й подати як контекст
     const intent = existingMd ? splitProtected(existingMd).body : null
     const anchors = facts.unsupported ? null : extractAnchors(src)
+    const promptSrc = resolvePromptSrc({ facts, estTokens, langExtractors, ext, src, file })
     let r = facts.unsupported
       ? await oneShotDoc(facts, src, model, LOCAL_TIMEOUT_MS, { intent })
-      : await orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, intent })
+      : await orchestratedDoc(facts, promptSrc, model, LOCAL_TIMEOUT_MS, { anchors, intent })
 
     // unsupported (vue/py до юніт-шару): скорер не застосовний — score=null, не degraded
     // (окрім refusal-пре-гейта — див. finishUnsupported).
@@ -586,7 +726,11 @@ export async function generateDoc(
     // E4: best-of-2 — один retry з вищою температурою, det-вибір кращого
     if (score < threshold && env.N_CURSOR_DOCGEN_BEST_OF !== '0') {
       try {
-        const r2 = await orchestratedDoc(facts, src, model, LOCAL_TIMEOUT_MS, { anchors, temperature: 0.5, intent })
+        const r2 = await orchestratedDoc(facts, promptSrc, model, LOCAL_TIMEOUT_MS, {
+          anchors,
+          temperature: 0.5,
+          intent
+        })
         const s2 = scoreDoc(r2.md, facts, { anchors, src })
         if (s2.score > score) {
           r = r2
@@ -604,12 +748,7 @@ export async function generateDoc(
     // доках, що ПРОЙШЛИ det-скорер (там ховаються false-positives). Scope: inaccurate.
     let judge = null
     if (JUDGE_ENABLED && score >= threshold) {
-      try {
-        judge = { ...(await judgeDoc(src, r.md, { chain })), model: JUDGE_MODEL }
-        if (judgeFailsDoc(judge)) issues = [...issues, `judge:inaccurate:${judge.confidence}`]
-      } catch (error) {
-        issues = [...issues, `judge:error: ${error.message.slice(0, 80)}`]
-      }
+      ;({ judge, r, score, issues } = await runJudgeGate({ r, score, issues, facts, anchors, src, model, chain }))
     }
 
     const degraded = score < threshold || judgeFailsDoc(judge)

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

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

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

@@ -1,11 +1,16 @@
 /** @see ./docs/docgen-prompts.md */
 
+import { env } from 'node:process'
+
 import { anchorsToPrompt } from '../docgen-extract-anchors/main.mjs'
 
 export const STYLE = [
   'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
   'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
-  'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
+  'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.',
+  // R9-профілактика: gemma-подібні малі моделі «озвучують завдання» перед відповіддю;
+  // явна заборона з прикладами різко знижує частоту (дет-зрізання у stripSection — страховка).
+  'Виведи ЛИШЕ текст секції. ЗАБОРОНЕНО починати з мета-фраз на кшталт «Ось оновлена чорнетка…», «Оновлений текст секції:», «Як технічний письменник, я створю…» — одразу перший змістовний рядок.'
 ].join(' ')
 
 /**
@@ -32,7 +37,9 @@ function factsSummary(facts) {
   if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
   // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence сигнали; жодних дефолтних
   // негативів (read-only «ні», «мережа: немає») — модель echo-їть їх як хибну гарантію.
-  if (m.readOnly) lines.push('Read-only: не пише (ФС/БД)')
+  // Scoped-формулювання readOnly (як у guaranteesFromMarkers): маркер file-local,
+  // безумовне «не пише» модель розганяє до хибного «гарантує безпечність» в Огляді.
+  if (m.readOnly) lines.push('Власних операцій запису (ФС/БД) у файлі немає (імпортовані модулі не аналізувались)')
   if (m.network) lines.push('Звертається до мережі')
   if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
   if (m.returnsFalsyOnFail) lines.push('За певних помилок повертає порожнє значення (напр. null) замість винятку')
@@ -81,10 +88,14 @@ export function sectionMessages(facts, src, anchors = null, intent = null) {
   const intentCtx = intentContext(intent)
   const multi = (facts.exports?.length || 0) > 1
 
-  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
+  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники.
+  // Мульти-експорт: «Публічний API» вже містить одно-рядкові описи кожної функції
+  // (Stage 1 — дослівно з JSDoc), тож пер-функційні пункти в Поведінці дублювали б
+  // його іншими словами. Натомість — крос-функціональний наратив: те, чого
+  // немає в жодному окремому JSDoc за визначенням.
   const exportNames = (facts.exports ?? []).map(e => e.name)
   const behaviorTask = multi
-    ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
+    ? 'крос-функціональний потік: у якому порядку і як функції взаємодіють між собою, звідки приходять дані і куди йдуть результати, спільні правила чи стан. НЕ переказуй кожну функцію окремим пунктом — одно-рядкові описи вже є в секції «Публічний API»'
     : 'нумерований алгоритм у бізнес-термінах'
   const onlyExports = exportNames.length
     ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
@@ -149,18 +160,20 @@ export function apiGapMessages(gapExports, anchors = null) {
 /**
  * R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
  * голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+ * Анкор-блок сюди НЕ підставляється (№8, бенч gemma-4): секції — окремі
+ * LLM-виклики, і коли анкори бачили обидва, кожен чесно вставляв «рівно один
+ * раз» → у документі виходило двічі (незграбні «посилаючись на…» в Огляді).
+ * Анкори живуть лише в Behavior-промпті; скорер R5 перевіряє документ цілком.
  * @param {object} facts факт-лист про файл
  * @param {string} behaviorText готовий текст секції «Поведінка»
- * @param {object|null} [anchors] анкори файлу
  * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
  * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
  */
-export function overviewMessages(facts, behaviorText, anchors = null, intent = null) {
+export function overviewMessages(facts, behaviorText, intent = null) {
   const factsTxt = factsSummary(facts)
-  const anch = anchorsBlock(anchors)
   const dedup = intent ? ' Не дублюй секцію «Призначення».' : ''
   return msgs(
-    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentContext(intent)}`,
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${intentContext(intent)}`,
     `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.${dedup}\n\nПОВЕДІНКА:\n${behaviorText}`
   )
 }
@@ -230,7 +243,13 @@ export function guaranteesFromMarkers(facts) {
   const lines = []
   // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence гарантії. Жодних
   // негативів/дефолтів (no-network, determinism) — їх не довести file-local аналізом.
-  if (m.readOnly) lines.push('- Read-only: не виконує операцій запису (ФС/БД).')
+  // readOnly — SCOPED-формулювання: маркер file-local (немає write-патернів у ЦЬОМУ
+  // файлі), але файл може викликати імпортовані модулі, які пишуть. Безумовне
+  // «Read-only: не виконує операцій запису» LLM-суддя (cloud-min) стабільно валив
+  // як inaccurate на всіх бенч-файлах efes 2026-07-21 — і мав рацію: це over-claim,
+  // який file-local аналіз не може підтвердити. Обмежене твердження — може.
+  if (m.readOnly)
+    lines.push('- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.')
   if (m.catchesErrors) lines.push('- Перехоплює помилки і не пропускає винятків назовні (fail-safe).')
   if (m.returnsFalsyOnFail) lines.push('- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.')
   if (m.caches) lines.push('- Кешує результати в межах одного прогону.')
@@ -254,3 +273,52 @@ export function oneShotMessages(facts, src) {
     `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
   )
 }
+
+/** Поріг (у токенах, ~4 байти/токен), після якого сирий src замінюється юніт-дайджестом. */
+export const UNIT_DIGEST_TOKENS = Number(env.N_CURSOR_DOCGEN_DIGEST_TOKENS ?? 2000) || 2000
+
+/** Скільки перших рядків тіла юніта потрапляє в дайджест, коли JSDoc порожній. */
+const DIGEST_BODY_LINES = 12
+
+/**
+ * №5 (бенч gemma-4): стислий юніт-дайджест великого файлу замість сирого src у
+ * Behavior-промпті. На ~6k токенів сирцю мала модель втрачає фокус (водянисті
+ * формулювання); дайджест подає структуру — імʼя, JSDoc, call-graph, тіло лише
+ * для непокритих JSDoc юнітів (перші рядки) — і тримає промпт компактним.
+ * @param {Array<{name:string, kind:string, exported:boolean, doc:string, calls:string[], body:string}>} units юніти файлу (extractUnits)
+ * @returns {string} текстовий дайджест для вставки замість повного src
+ */
+export function buildUnitDigest(units) {
+  const parts = [
+    'СТИСЛИЙ ДАЙДЖЕСТ ФАЙЛУ (повний код не подано — файл завеликий; описуй ЛИШЕ те, що видно з дайджесту):'
+  ]
+  for (const u of units) {
+    const head = `### ${u.name} (${u.exported ? 'export ' : ''}${u.kind})`
+    const lines = [head]
+    if (u.doc) lines.push(`JSDoc: ${u.doc}`)
+    if (u.calls?.length) lines.push(`викликає: ${u.calls.join(', ')}`)
+    if (!u.doc && u.body) {
+      const bodyLines = u.body.split('\n')
+      const trimmed = bodyLines.slice(0, DIGEST_BODY_LINES).join('\n')
+      lines.push('```', trimmed + (bodyLines.length > DIGEST_BODY_LINES ? '\n…' : ''), '```')
+    }
+    parts.push(lines.join('\n'))
+  }
+  return parts.join('\n\n')
+}
+
+/**
+ * №6 — judge-refine: один локальний refine-прохід за конкретними зауваженнями
+ * LLM-судді (замість лише маркування degraded). Суддя вже сформулював, ЩО саме
+ * хибне (`reason`) — мала модель добре виправляє точкові твердження, коли їй
+ * сказано, які саме.
+ * @param {string} doc машинні секції доки (без захищеного «Призначення»)
+ * @param {string} reason зауваження судді (verdict.reason)
+ * @returns {Array<{role:string,content:string}>} messages-масив для LLM
+ */
+export function judgeRefineMessages(doc, reason) {
+  return msgs(
+    STYLE,
+    `Рецензент знайшов у документації неточності:\n${reason}\n\nВиправ ЛИШЕ хибні твердження — прибери або переформулюй їх так, щоб вони відповідали дійсності. Збережи структуру (усі ## заголовки), мову й решту тексту без змін. Поверни ПОВНИЙ виправлений markdown-документ, без преамбул.\n\nДОКУМЕНТ:\n${doc}`
+  )
+}

package/rules/text/run-v8r/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/text/run-v8r/main.mjs
 docgen:
-  crc: 91a9608d
+  crc: 10f448a2
   model: manual
 ---