@7n/rules 1.38.0 → 1.40.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [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
+
+- workspace_root: канон одного кореневого uv workspace на репозиторій (дзеркало rust/workspace_root), main.json auto-glob розширено на вкладені pyproject.toml
+
 ## [1.38.0] - 2026-07-21
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.38.0",
+  "version": "1.40.0",
   "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
 ---
 

package/scripts/utils/docs/index.md

@@ -20,6 +20,7 @@ resource: npm/scripts/utils/
 | [resolve-js-root.mjs](resolve-js-root.md)                   | JS Module |
 | [spawn-async.mjs](spawn-async.md)                           | JS Module |
 | [test-helpers.mjs](test-helpers.md)                         | JS Module |
+| [uv-workspace.mjs](uv-workspace.md)                         | JS Module |
 | [walk-cache.mjs](walk-cache.md)                             | JS Module |
 | [walkDir.mjs](walkDir.md)                                   | JS Module |
 | [with-lock.mjs](with-lock.md)                               | JS Module |

package/scripts/utils/docs/uv-workspace.md

@@ -0,0 +1,34 @@
+---
+type: JS Module
+title: uv-workspace.mjs
+resource: npm/scripts/utils/uv-workspace.mjs
+docgen:
+  crc: b7602da3
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`readPyprojectManifest` читає `pyproject.toml` і повертає маніфест uv workspace, а `resolveUvWorkspaceMemberDirs` резолвить каталоги з `[tool.uv.workspace].members` та `.exclude` за тією самою glob-семантикою, що й у Cargo workspaces. Це read-only, fail-safe набір спільних T0-утиліт: він не пише у ФС чи БД, не кидає винятків назовні та для частини помилок повертає порожнє значення замість помилки.
+
+## Поведінка
+
+- `readPyprojectManifest` — читає `pyproject.toml` для uv workspace і повертає розпарсений manifest або `null`, якщо файл відсутній чи TOML невалідний.
+- `resolveUvWorkspaceMemberDirs` — перетворює `members` і `exclude` uv workspace на список абсолютних каталогів із власним `pyproject.toml`, враховуючи літеральні шляхи та прості glob-патерни.
+
+## Публічний API
+
+- readPyprojectManifest — Розпарсений pyproject.toml або null (файл відсутній чи невалідний TOML).
+- resolveUvWorkspaceMemberDirs — Резолвить `[tool.uv.workspace].members`/`.exclude`-патерни (літеральні шляхи й прості
+glob з `*`) відносно `rootDir` у список абсолютних каталогів, що мають власний
+pyproject.toml. Без повної glob-семантики uv — лише `*`-сегменти й літерали.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/scripts/utils/uv-workspace.mjs

@@ -0,0 +1,56 @@
+/**
+ * Спільні T0 (без spawn `uv`) утиліти для роботи з uv workspace-структурою: читання
+ * `pyproject.toml`, резолв `[tool.uv.workspace].members`/`.exclude`-glob-патернів у
+ * каталоги. Дзеркалить `cargo-workspace.mjs` (rust/workspace_root) — uv workspaces
+ * навмисно змодельовані на Cargo workspaces, glob-семантика `members`/`exclude` та сама.
+ * Не імпортується напряму з rust-боку (окремі плагіни) — дублювання свідоме.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+
+import { parse as parseToml } from 'smol-toml'
+
+import { scanGlob } from './glob-compat.mjs'
+
+const TRAILING_SLASH_RE = /\/$/
+
+/**
+ * Розпарсений pyproject.toml або null (файл відсутній чи невалідний TOML).
+ * @param {string} absPath абсолютний шлях до pyproject.toml
+ * @returns {Promise<Record<string, unknown>|null>} розпарсений маніфест або null
+ */
+export async function readPyprojectManifest(absPath) {
+  if (!existsSync(absPath)) return null
+  try {
+    return parseToml(await readFile(absPath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Резолвить `[tool.uv.workspace].members`/`.exclude`-патерни (літеральні шляхи й прості
+ * glob з `*`) відносно `rootDir` у список абсолютних каталогів, що мають власний
+ * pyproject.toml. Без повної glob-семантики uv — лише `*`-сегменти й літерали.
+ * @param {string} rootDir корінь workspace (каталог з pyproject.toml, де живе `[tool.uv.workspace]`)
+ * @param {string[]} patterns патерни з `members`/`exclude`
+ * @returns {Promise<string[]>} абсолютні шляхи (без дублікатів)
+ */
+export async function resolveUvWorkspaceMemberDirs(rootDir, patterns) {
+  const found = new Set()
+  for (const pattern of patterns ?? []) {
+    const norm = pattern.replace(TRAILING_SLASH_RE, '')
+    if (norm.includes('*')) {
+      // Патерн для pyproject.toml напряму (не для каталогів) — деякі раннери (Bun.Glob)
+      // за замовчуванням матчать лише файли, тож патерн на голий каталог даватиме 0 збігів.
+      for await (const relManifest of scanGlob(`${norm}/pyproject.toml`, rootDir)) {
+        found.add(resolve(rootDir, dirname(relManifest)))
+      }
+      continue
+    }
+    const abs = resolve(rootDir, norm)
+    if (existsSync(`${abs}/pyproject.toml`)) found.add(abs)
+  }
+  return [...found]
+}