@nitra/cursor 5.1.0 → 5.2.1

package/skills/doc-files/js/docs/docgen-prompts.md

@@ -0,0 +1,32 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-prompts.mjs
+  crc: c454d2a6
+---
+
+# docgen-prompts
+
+## Огляд
+
+Промптовий шар local-only конвеєра файлових док: будує messages-набори для секційної генерації, критики й переписування, а секцію «Гарантії поведінки» формує детерміновано без LLM. Весь стиль документа (українська, поведінковість, заборона сигнатур) зашитий у спільний system-блок.
+
+## Поведінка
+
+1. Для кожної секції збирається мінімальний контекст: «Огляд» — лише людиночитний витяг фактів (без коду), «Поведінка» — єдина секція з повним кодом файлу у вікні, «Публічний API» — лише список експортів з їхніми описами. Анкори (URL, константи, маркери, приклади) додаються окремим блоком, коли вони є.
+2. Факт-лист перекладається в негативні й позитивні твердження для моделі: свідомі пропуски шляхів, read-only, перехоплення помилок, явне «Кешування: НЕМАЄ — не згадуй кеш» — щоб відсікти типові галюцинації ще в промпті.
+3. Критик отримує чорнетку секції і закритий список критеріїв дефектів (generic-фрази, пропущені анкори, граматика, підзаголовки, скопійовані сигнатури, вигадані факти); відповідь — список проблем або `NONE`. Переписувач отримує чорнетку разом зі списком проблем і повертає лише оновлений текст.
+4. «Гарантії поведінки» складаються шаблоном з маркерів факт-листа (read-only, fail-safe, кешування, пропуски шляхів, відсутність мережі) — нуль запитів і нуль generic-фраз; за відсутності маркерів — твердження про детермінованість.
+
+## Публічний API
+
+- `sectionMessages` — секційні набори messages з мінімальним контекстом під кожну секцію.
+- `criticMessages` / `refineMessages` — пара критика й переписувача для одного циклу уточнення секції.
+- `guaranteesFromMarkers` — детермінований текст секції гарантій з маркерів.
+- `oneShotMessages` — один запит на весь документ для нестандартних структур файлів.
+- `STYLE` — спільний system-блок стилю.
+
+## Гарантії поведінки
+
+- Код файлу потрапляє лише у промпт секції «Поведінка» й у one-shot — решта секцій працюють на факт-листі.
+- Формування промптів детерміноване: однакові факти й код → однакові messages.
+- Не звертається до мережі й не виконує LLM-викликів — лише будує тексти.

package/skills/doc-files/js/docs/docgen-scan.md

@@ -0,0 +1,25 @@
+---
+docgen:
+  source: npm/skills/doc-files/js/docgen-scan.mjs
+  crc: b517ab25
+---
+
+# docgen-scan
+
+## Огляд
+
+Сканер кодових файлів і детектор стану файлових док: які джерела підлягають документуванню, де лежить їхня дока, що застаріло, що degraded. Працює і як бібліотека для batch-генерації, і як CLI (`doc-files scan` / `doc-files check`) для хуків.
+
+## Поведінка
+
+1. Рекурсивний обхід від кореня збирає кодові файли (`js`/`mjs`/`ts`/`vue`/`py`), пропускаючи тести, оголошення типів, ignore-дерева і теки `docs/`; для кореня з system-wide docs-layout файлові доки на верхньому рівні не плануються.
+2. Для кожного джерела обчислюється шлях доки (`<dir>/docs/<stem>.md`) і стан застарілості за контрольною сумою.
+3. `check` працює в режимах: `--hook` — один файл зі stdin-payload редакторського хука; `--git` — змінені відносно HEAD джерела як Stop-гейт із порогом великого прогону (`--max`, дефолт `50` або `N_CURSOR_DOC_FILES_GATE_MAX`: більше застарілих — попередження без блоку); явні шляхи — точкова перевірка.
+4. Застарілі доки → exit-код `2` зі списком і підказкою перегенерації; усе свіже або великий прогін — `0`.
+5. `check --degraded` — інформаційний звіт (exit `0`): свіжі за сумою доки з оцінкою нижче порогу, з кодами проблем і підказкою про `gen --retry-degraded`. Degraded — видимий борг, не гейт.
+
+## Гарантії поведінки
+
+- Сканер read-only: жодних записів у дерево.
+- Рішення «застаріла/свіжа» детерміноване і залежить лише від вмісту джерела й frontmatter доки.
+- Stop-гейт ніколи не блокує масовий перший прогін понад поріг — захист від нескінченного блокування задач.

package/skills/doc-files/js/units-js.mjs

@@ -0,0 +1,139 @@
+/** @see ./docs/units-js.md */
+
+import { parseProgramOrNull, walkAstWithAncestors } from '../../../scripts/utils/ast-scan-utils.mjs'
+
+// JSDoc-блок, що стоїть впритул перед позицією (лише пробіли між ними).
+const JSDOC_BEFORE_RE = /\/\*\*(?:(?!\*\/)[\s\S])*\*\/\s*$/
+const JSDOC_OPEN_RE = /^\s*\/\*\*?/
+const JSDOC_CLOSE_RE = /\*\/\s*$/
+const STAR_PREFIX_RE = /^\s*\*?\s?/
+
+/**
+ * Очищає JSDoc від обрамлення `/** *​/` і `*`-префіксів.
+ * @param {string} raw сирий блок або порожній рядок
+ * @returns {string} текст опису без тегів-обрамлення
+ */
+function cleanDoc(raw) {
+  if (!raw) return ''
+  return raw
+    .replace(JSDOC_OPEN_RE, '')
+    .replace(JSDOC_CLOSE_RE, '')
+    .split('\n')
+    .map(l => l.replace(STAR_PREFIX_RE, '').trimEnd())
+    .join('\n')
+    .trim()
+}
+
+/**
+ * JSDoc, що передує позиції `start` у джерелі (або порожній рядок).
+ * @param {string} src вміст файлу
+ * @param {number} start зміщення початку декларації
+ * @returns {string} очищений опис
+ */
+function precedingDoc(src, start) {
+  const m = src.slice(0, start).match(JSDOC_BEFORE_RE)
+  return cleanDoc(m ? m[0] : '')
+}
+
+/**
+ * Імʼя функції, що викликається (проста Identifier або `obj.method`).
+ * @param {Record<string, unknown>} node CallExpression
+ * @returns {string|null} імʼя callee або null
+ */
+function calleeName(node) {
+  const c = node.callee
+  if (!c || typeof c !== 'object') return null
+  if (c.type === 'Identifier') return c.name
+  if (c.type === 'MemberExpression' && !c.computed && c.property?.type === 'Identifier') return c.property.name
+  return null
+}
+
+/**
+ * Множина імен, що викликаються у тілі вузла (сирі callee — фільтрація на ребра
+ * call-graph робиться у `extractUnitsJs` після збору всіх імен юнітів).
+ * @param {unknown} node AST-вузол юніта
+ * @returns {Set<string>} імена викликів
+ */
+function collectCalls(node) {
+  const names = new Set()
+  walkAstWithAncestors(node, [], n => {
+    if (n.type === 'CallExpression') {
+      const name = calleeName(n)
+      if (name) names.add(name)
+    }
+  })
+  return names
+}
+
+/**
+ * Будує юніт із декларації, додає у `units`. Розпізнає function/class та
+ * const-функції (`const x = () => {}` / `function expression`).
+ * @param {Record<string, unknown>} decl декларація (function/class/variable)
+ * @param {boolean} exported чи експортується
+ * @param {number} docStart зміщення для пошуку JSDoc (зовнішній export-вузол)
+ * @param {string} src вміст файлу
+ * @param {Array<object>} units акумулятор
+ * @returns {void}
+ */
+function pushUnits(decl, exported, docStart, src, units) {
+  if (!decl || typeof decl !== 'object') return
+  const doc = precedingDoc(src, docStart)
+  if (decl.type === 'FunctionDeclaration' || decl.type === 'ClassDeclaration') {
+    const name = decl.id?.name
+    if (!name) return
+    units.push({
+      name,
+      kind: decl.type === 'ClassDeclaration' ? 'class' : 'function',
+      exported,
+      span: { start: decl.start, end: decl.end },
+      body: src.slice(decl.start, decl.end),
+      calls: collectCalls(decl),
+      doc
+    })
+    return
+  }
+  if (decl.type === 'VariableDeclaration') {
+    for (const d of decl.declarations ?? []) {
+      const init = d.init
+      const isFn = init && (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression')
+      if (!isFn || d.id?.type !== 'Identifier') continue
+      units.push({
+        name: d.id.name,
+        kind: 'const',
+        exported,
+        span: { start: init.start, end: init.end },
+        body: src.slice(init.start, init.end),
+        calls: collectCalls(init),
+        doc
+      })
+    }
+  }
+}
+
+/**
+ * Юніт-шар для js/mjs/ts: top-level функції/класи/const-функції з тілом, JSDoc,
+ * прапором експорту і ребрами call-graph (виклики ІНШИХ юнітів у тілі).
+ * @param {string} src вміст файлу
+ * @param {string} [relPath] шлях (для вибору мови oxc)
+ * @returns {Array<{name:string, kind:string, exported:boolean, span:{start:number,end:number}, body:string, calls:string[], doc:string}>|null} юніти або null, якщо файл не парситься
+ */
+export function extractUnitsJs(src, relPath = 'scan.ts') {
+  const program = parseProgramOrNull(src, relPath)
+  if (!program || !Array.isArray(program.body)) return null
+
+  const units = []
+  for (const node of program.body) {
+    if (node.type === 'ExportNamedDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else if (node.type === 'ExportDefaultDeclaration' && node.declaration) {
+      pushUnits(node.declaration, true, node.start, src, units)
+    } else {
+      pushUnits(node, false, node.start, src, units)
+    }
+  }
+
+  // Ребра call-graph: лишаємо тільки виклики інших внутрішніх юнітів
+  const names = new Set(units.map(u => u.name))
+  for (const u of units) u.calls = [...u.calls].filter(n => names.has(n) && n !== u.name)
+  return units
+}

package/skills/doc-files/js/units.mjs

@@ -0,0 +1,19 @@
+/** @see ./docs/units.md */
+
+import { extractUnitsJs } from './units-js.mjs'
+
+const JS_EXT = new Set(['js', 'mjs', 'ts', 'jsx', 'tsx', 'cts', 'mts'])
+
+/**
+ * Мовно-агностичний фасад юніт-шару (Інкремент 1). Диспатчить за розширенням:
+ * js/mjs/ts → oxc; vue/py — додаються наступними кроками (поки `null` → виклик
+ * відкочується на whole-file шлях, як і раніше).
+ * @param {string} src вміст файлу
+ * @param {string} relPath шлях файлу
+ * @returns {Array<object>|null} юніти або null, якщо мова ще не підтримана / файл не парситься
+ */
+export function extractUnits(src, relPath) {
+  const ext = (relPath.split('.').pop() || '').toLowerCase()
+  if (JS_EXT.has(ext)) return extractUnitsJs(src, relPath)
+  return null
+}

package/skills/doc-files/meta.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false, "requireRoot": true }

package/skills/fix/js/docs/llm-worker.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/fix/js/llm-worker.mjs
+  crc: 8317f878
+---
+
 # llm-worker.mjs
 
 ## Огляд

package/skills/fix/js/docs/orchestrator.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/fix/js/orchestrator.mjs
+  crc: 8b7a7de5
+---
+
 # orchestrator.mjs
 
 ## Огляд

package/skills/fix/js/llm-worker.mjs

@@ -12,7 +12,7 @@ import { callOmlx, isOmlxModel } from '../../../lib/omlx.mjs'
 export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
-const JSON_CODE_BLOCK_RE = /```(?:json)?\s*([\s\S]*?)```/
+const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
 
 /**
  * Витягує відносні шляхи файлів із violation output.
@@ -35,7 +35,7 @@ function extractFilePaths(output) {
   }
 
   // Патерн без workspace: просто path/to/file.ext або ./file.ext
-  const re = /(?:^|\s)(\.?[\w][\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  const re = /(?:^|\s)(\.?\w[\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
   for (const m of output.matchAll(re)) {
     const p = m[1]
     if (!seen.has(p)) {
@@ -116,7 +116,7 @@ function callModel(prompt, model) {
         error: [
           `pi: немає ключа для ${provider}.`,
           `Встановіть N_CLOUD_MIN_MODEL=provider/model-id`,
-          `(напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, ollama/gemma3:4b)`,
+          `(напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, ollama/gemma3:4b)`
         ].join(' ')
       }
     }

package/skills/fix/js/orchestrator.mjs

@@ -20,7 +20,7 @@ export async function runOrchestratorCli(args, cwd) {
 
   const maxIterIdx = args.indexOf('--max-iter')
   const maxIter =
-    maxIterIdx === -1 ? DEFAULT_MAX_ITER : (Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER)
+    maxIterIdx === -1 ? DEFAULT_MAX_ITER : Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER
   const skipIdxs = new Set(maxIterIdx === -1 ? [] : [maxIterIdx, maxIterIdx + 1])
   const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
 

package/skills/start-check/js/check.mjs

@@ -67,8 +67,8 @@ export async function scanStartWorkspaces(cwd) {
  * @param {string} log обʼєднаний stdout+stderr
  * @returns {{ready:boolean, firstError:string|null, logTail:string}} витяг
  */
-export function parseStartLog(log) {
-  const text = log ?? ''
+export function parseStartLog(log = '') {
+  const text = log
   const lines = text.split('\n')
   const firstError = lines.find(l => ERROR_RE.test(l))?.trim() ?? null
   const logTail = lines
@@ -137,7 +137,9 @@ export async function runWorkspaceStart(cwd, workspace, opts = {}) {
 
   // server: успіх = дожив до кінця grace (timedOut) або встиг віддати рядок готовності.
   // cli: успіх = чистий вихід 0 у межах grace.
-  const status = type === 'server' ? (timedOut || ready ? 'OK' : 'FAIL') : exitCode === 0 ? 'OK' : 'FAIL'
+  let status
+  if (type === 'server') status = timedOut || ready ? 'OK' : 'FAIL'
+  else status = exitCode === 0 ? 'OK' : 'FAIL'
 
   return {
     workspace,

package/skills/start-check/js/docs/check.md

@@ -1,3 +1,9 @@
+---
+docgen:
+  source: npm/skills/start-check/js/check.mjs
+  crc: 1809127a
+---
+
 # check.mjs
 
 ## Огляд

package/skills/docgen/SKILL.md

@@ -1,224 +0,0 @@
----
-name: docgen
-description: >-
-  Обходить проєкт і для кожного кодового файлу (js/mjs/ts/vue/py) пише лаконічну поведінкову українську md-документацію у теку docs/ поряд із кодом — диспатчить окремого субагента на кожен файл, за правилами adr/ci4
----
-
-# docgen — генерація документації по файлах
-
-## Мета
-
-Для кожного кодового файлу проєкту створити лаконічну поведінкову `.md`-документацію у теці `docs/`
-**поряд із самим файлом** (`<dir>/docs/<stem>.md`). Документацію пише **окремий субагент**
-на кожен файл — не один прохід, а батч-диспатч. Джерело правди стилю — правила `adr` і
-`ci4` (`docs/explanation`/`docs/adr`-каталоги з тих правил **не застосовуємо** — доку
-кладемо локально поряд із кодом).
-
-Документація — **трирівнева**, рівні виконуються строго послідовно:
-
-1. **Tier 1 — файли**: `<dir>/docs/<stem>.md`, субагент на файл (нижче).
-2. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
-3. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
-   виділяє бізнес-домени й пише файл на кожен домен.
-
-Агрегат ніколи не випереджає джерело: Tier 2 — лише після завершення всього Tier 1,
-Tier 3 — лише після завершення всього Tier 2.
-
-## ⚠️ Паралелізм
-
-Диспатч субагентів — **батчами по 5 одночасно**. Не запускати весь список одразу
-(перевантаження). Кожен субагент пише свій окремий файл — спільного стану немає, гонок
-за файли немає.
-
-Рівні строго послідовні: Tier 2 стартує лише після завершення всього Tier 1, Tier 3 —
-лише після всього Tier 2. Усередині Tier 1 і Tier 2 — батчі по 5. Tier 3 — один субагент.
-
-## Передумова
-
-- Поточна директорія — корінь проєкту, який документуємо.
-- Доступний `npx @nitra/cursor` (пакет `@nitra/cursor` встановлено або через npx).
-
-## Workflow
-
-### Крок 1: Зібрати список файлів
-
-```bash
-npx @nitra/cursor docgen scan
-```
-
-Команда друкує JSON-масив об'єктів. Усі шляхи в ньому — відносні до кореня проєкту:
-
-```json
-[{ "sourcePath": "src/lib/foo.js", "docPath": "src/lib/docs/foo.md", "exists": false }]
-```
-
-Розпарси JSON.
-
-### Крок 2: Відфільтрувати вже описані
-
-За замовчуванням **пропусти** елементи з `"exists": true`. Перегенеровуй їх лише якщо
-користувач явно попросив `--overwrite` (тоді обробляй усі). `--overwrite` — **не** прапор
-`docgen scan`: scanner лише лістить файли, а рішення «пропустити чи перегенерувати» приймаєш
-ти тут, фільтруючи за полем `exists`.
-
-Якщо після фільтра список порожній — зупинись:
-
-```
-✓ Усі кодові файли вже мають документацію. Нічого робити.
-```
-
-Запам'ятай `total = довжина відфільтрованого списку`.
-
-### Крок 3: Диспатч субагентів батчами по 5
-
-Розбий список на батчі по 5 елементів. Для кожного батчу запусти **до 5 субагентів
-одночасно (в одному повідомленні)**, дочекайся завершення батчу, переходь до наступного.
-
-Промпт кожного субагента (підстав `sourcePath` і `docPath`):
-
-```
-Напиши лаконічну технічну документацію для одного файлу коду — орієнтовану на поведінку, не реалізацію.
-
-ФАЙЛ-ДЖЕРЕЛО: <sourcePath>
-ЗАПИСАТИ В: <docPath>
-
-Кроки:
-1. Прочитай файл <sourcePath> повністю.
-2. Створи теку для <docPath>, якщо її немає.
-3. Запиши markdown-документ у <docPath> за правилами нижче.
-
-Правила документа (за adr/ci4):
-- Мова — УКРАЇНСЬКА для всього тексту (заголовки, абзаци, таблиці). Code identifiers,
-  шляхи, імена API, команди — лишай як у коді (зазвичай ASCII).
-- ЧИСТИЙ Markdown. Жодних HTML-обгорток (<div>/<span>/класів) — токен-ефективність.
-- ФОКУС НА ПОВЕДІНЦІ, не реалізації. Пиши ЩО і НАВІЩО, а не як саме це зроблено.
-- НЕ перелічуй модулі стандартної бібліотеки (node:fs, node:path, node:crypto, python stdlib
-  тощо) — вони не несуть бізнес-значення. Зовнішні залежності (npm-пакети, внутрішні модулі)
-  згадуй лише якщо їхня роль не очевидна з контексту.
-- НЕ перелічуй внутрішні назви допоміжних функцій/змінних — описуй їхню роль і поведінку.
-  Імена публічних exports згадуй лише коли export — справжня точка інтеграції, яку кличуть
-  ззовні. Для дрібних/листкових модулів з однією відповідальністю опиши роль поведінково,
-  БЕЗ сигнатур, таблиць типів і переліку параметрів — це деталі реалізації.
-- Контекстна незалежність: кожна секція самодостатня. Уникай «як вище», «ця функція», «той сервіс».
-- Секції (включай лише доречні — порожніх не вигадуй):
-  ## Огляд — 1-3 речення: що файл робить і навіщо він існує (роль у системі). Згадай
-    ключову семантику, якщо вона визначає сенс файлу (opt-in/gate, кеш, ідемпотентність тощо).
-  ## Поведінка — покроковий алгоритм у бізнес-термінах (не деталі реалізації).
-    Нумерований список: що відбувається, умови, гілки логіки. Якщо файл керується
-    конфігом чи форматом даних — наведи короткий приклад (тільки реальний з коду).
-  ## Публічний API — ЛИШЕ якщо модуль має нетривіальну зовнішню поверхню, яку називають
-    споживачі. Для кожного export: назва + що робить. Без сигнатур і таблиць типів.
-    Не дублюй ## Поведінка. Для модуля з однією функцією-предикатом цю секцію пропусти.
-  ## Де використовується — де в системі цей файл вживається (якщо відомо з коду).
-  ## Гарантії поведінки — інваріанти й крайові випадки: що гарантовано (read-only,
-    не кидає винятків, fail-safe-значення за замовчуванням, безпечна обробка поганих даних)
-    і що стається при відсутніх ресурсах чи некоректному вводі. Пропусти, якщо таких гарантій немає.
-- Для .vue додай ## Інтерфейс компонента — props (типи, defaults), emits, slots, реактивний стан.
-- НЕ вигадуй деталей, яких немає в коді.
-- Мета — Behavior Test: читач розуміє, що робить файл і як він вписується в систему,
-  без потреби читати реалізацію.
-
-Поверни лише підтвердження, що файл <docPath> записано.
-```
-
-### Крок 4: Tier 2 — module-summary
-
-Після завершення **всіх** батчів Tier 1 зібрати список модулів:
-
-```bash
-npx @nitra/cursor docgen modules
-```
-
-Команда друкує JSON-масив:
-
-```json
-[
-  {
-    "moduleRoot": "/abs/npm/rules/adr",
-    "relRoot": "npm/rules/adr",
-    "slug": "npm-rules-adr",
-    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
-    "members": ["npm/rules/adr/index.mjs"],
-    "exists": false
-  }
-]
-```
-
-module-summary **завжди регенерується** (це агрегат — поле `exists` ігноруй). Розбий модулі на батчі по 5 і диспатч субагентів. Промпт кожного (підстав `relRoot`, `docPath`, `members`):
-
-```
-Напиши module-summary для одного логічного модуля.
-
-МОДУЛЬ: <relRoot>
-ЗАПИСАТИ В: <docPath>
-ФАЙЛИ МОДУЛЯ (members): <members>
-
-Кроки:
-1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
-   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
-   в самі файли.
-2. Створи теку для <docPath>, якщо її немає.
-3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
-   (українська, чистий Markdown, контекстна незалежність, без HTML).
-
-Секції module-summary:
-## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
-## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
-   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
-## Публічний API — що модуль експортує назовні.
-## Внутрішній потік — як компоненти модуля взаємодіють.
-## Підмодулі — вкладені модулі, якщо є.
-
-Поверни лише підтвердження, що файл <docPath> записано.
-```
-
-### Крок 5: Tier 3 — доменні доки
-
-Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
-У промпт підстав конкретний перелік шляхів module-summary (<module_root>/docs/ARCHITECTURE.md
-кожного модуля з виводу `docgen modules`), а не інструкцію їх шукати. Промпт:
-
-```
-Синтезуй доменну документацію бізнес-процесів проєкту.
-
-ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>
-
-Кроки:
-1. Прочитай усі module-summary.
-2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
-3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
-   - назва файлу — короткий kebab-slug домену;
-   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
-     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
-     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
-   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.
-
-Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).
-
-Поверни перелік створених файлів docs/<домен>.md.
-```
-
-### Крок 6: Підсумок
-
-Після всіх батчів виведи:
-
-```
-✓ docgen завершено.
-Tier 1 (файли): описано <N>, пропущено <S>, помилок <E>.
-Tier 2 (модулі): <M> module-summary.
-Tier 3 (домени): <D> доменних доків у docs/.
-```
-
-Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
-Помилка одного файлу не зупиняє решту — обробляй усі батчі до кінця.
-
-## Нотатки
-
-- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
-- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`,
-  `.claude`, усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`.
-  Кореневий repo `docs/` — system-wide only: file-level docs туди не пишуться, і Tier 1
-  має трактувати цей корінь як повністю нецільовий.
-- Список glob-ів для ignore живе в окремому snippet-модулі
-  `npm/skills/docgen/js/docgen-ignore.mjs` (`DOCGEN_IGNORE_GLOBS`).
-  Scanner лише читає цей список.

package/skills/docgen/bench/etalon/firebase_hosting.md

@@ -1,19 +0,0 @@
-# firebase_hosting.mjs
-
-## Огляд
-
-Перевірка-концерн правила abie: у підкаталогах першого рівня репозиторію не повинно бути артефактів Firebase Hosting (`.firebaserc`, `firebase.json`, `.firebase/`), бо `abie.mdc` забороняє Firebase Hosting. Сам корінь репозиторію не перевіряється — там ці імена можуть належати суміжним проєктам.
-
-## Поведінка
-
-1. Прочитати список елементів кореня репозиторію. Якщо каталог не читається — зафіксувати помилку (fail) і завершитися.
-2. Відібрати підкаталоги першого рівня, пропустивши `.git` і `node_modules`.
-3. У кожному такому підкаталозі перевірити наявність заборонених імен: файлів `.firebaserc`, `firebase.json` і каталогу `.firebase/`. Кожна знахідка — окремий fail.
-4. Якщо жодного порушення не знайдено — зафіксувати pass.
-5. Повернути підсумковий exit-код.
-
-## Гарантії поведінки
-
-- Read-only: лише перелічує й перевіряє існування шляхів.
-- Помилка читання кореня не валить процес винятком, а стає fail.
-- Перевіряється лише перший рівень; корінь і глибші рівні поза охопленням.

package/skills/docgen/bench/etalon/k8s-tree.md

@@ -1,24 +0,0 @@
-# k8s-tree.mjs
-
-## Огляд
-
-Обхід Kubernetes-дерева для перевірок abie з кешуванням на час одного прогону. Знаходить YAML під сегментом `k8s/` і визначає каталоги з `Deployment`. Перший виклик платить за обхід; наступні концерни прогону беруть із кешу.
-
-## Поведінка
-
-1. Пошук маніфестів: рекурсивно обійти дерево, відібравши `.yaml`/`.yml` під сегментом `k8s/`; `.github/` свідомо пропускається. Результат відсортований.
-2. Каталоги з Deployment: розпарсити передані YAML, відібрати `kind: Deployment`, зібрати унікальні каталоги.
-3. Кешування: обидві операції кешуються module-level singleton-ом за ключем із входів; повтор без I/O.
-4. Пошкоджені YAML за замовчуванням мовчки пропускаються; репортер передає викликач.
-
-## Публічний API
-
-- `findK8sYamlFiles` — відсортований список YAML під `k8s/` (з кешем, пропуск `.github/`).
-- `collectDeploymentDirs` — множина каталогів із Deployment (кеш, опц. репортер помилок).
-
-## Гарантії поведінки
-
-- Read-only щодо проєкту.
-- Стійкість до пошкоджених YAML: помилкові документи пропускаються, обхід не переривається.
-- Детермінований вивід (стабільне сортування).
-- Кеш у межах прогону; повторні виклики безкоштовні.

package/skills/docgen/bench/etalon/overlay-paths.md

@@ -1,24 +0,0 @@
-# overlay-paths.mjs
-
-## Огляд
-
-Набір чистих path-хелперів для overlay-перевірок правила abie: класифікація шляхів (ua-overlay проти base-шару), виведення каталогу пакета з overlay-шляху, умовні питання правила (чи потрібен HTTPRoute, чи є Deployment). Уся логіка — над рядками/шляхами та перевіркою існування файлів; YAML не парситься.
-
-## Поведінка
-
-- ua-overlay: шлях закінчується на `ua/kustomization.yaml`; base-шар — за сегментом `base/`.
-- Каталог пакета: з `…/k8s/ua/kustomization.yaml` виділяється батько `k8s/`; без збігу — немає результату.
-- HTTPRoute-gate: вимога лише для Vite-пакетів (є `vite.config.{js,mjs,ts}`).
-- Deployment: чи хоч один каталог із Deployment лежить у `k8s/` цього пакета.
-- base-шар: yaml під `<пакет>/k8s/` і не в `ua/`.
-- Шляхи нормалізуються до posix (`\`→`/`).
-
-## Публічний API
-
-- `isUaKustomizationPath`, `abiePackageDirFromK8sOverlay`, `abieOverlayRequiresHttpRouteByVite`, `abieOverlayK8sTreeHasDeployment`, `isAbieK8sBaseYamlPath`, `isK8sYamlInAbiePackageExcludingUaOverlay`.
-
-## Гарантії поведінки
-
-- Read-only, без побічних ефектів.
-- Невідповідність шаблону → негативний/порожній результат, не виняток.
-- Незалежність від ОС (розділювачі зводяться до `/`).