---
name: doc-files
description: >-
  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (розширення декларують lang-плагіни: js/mjs/ts/vue — lang-js, rs/py — lang-rust/lang-python) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
version: '1.0'
---

# doc-files — файлова документація (обовʼязковий крок)

## Мета

Для кожного кодового файлу проєкту тримати **актуальну** лаконічну поведінкову `.md`-документацію
у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
задачі** — як `lint`: після зміни коду його дока має бути перегенерована.

Застарілість визначається **детерміновано за CRC evidence**: кожна дока несе у frontmatter
контрольну суму source + повʼязаних test/spec-файлів на момент генерації. Без повʼязаних
тестів це звичайний CRC source. Дока **застаріла**, якщо її немає або поточний evidence CRC
не збігається з `crc` у frontmatter.

```markdown
---
docgen:
  source: src/lib/foo.js
  crc: a3f1c9e0
---

## Огляд

…
```

## Оркестрацію веде JS, не модель; конвеєр — local-only

Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе у JS-оркестрації
`lint doc-files`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
запустити генерацію і прочитати підсумок.

Конвеєр **суто локальний** (ADR `260610-2228`): будь-який файл генерується локальною
моделлю (`omlx/…` напряму), хмарних ескалацій немає. Якщо det-оцінка нижча за поріг —
дока все одно пишеться з **degraded-маркером** (`score`/`issues` у frontmatter, CRC свіжий),
а перегенерація таких док — окремою командою пізніше.

## Передумова

- Поточна директорія — корінь проєкту (`requireRoot`), не worktree.
- Доступний `npx @7n/rules`.

## Workflow

### Крок 1: Генерація застарілих/відсутніх док

```bash
npx @7n/rules lint doc-files
```

Команда запускає doc-files лінтер у fix-режимі (весь репо): перевіряє omlx
(preflight: «сервер лежить» / «модель не влазить у пам'ять зайнятої машини» /
«потрібен API-ключ» → одна зрозуміла зупинка замість лавини «✗») → фільтрує застарілі
(`stale`) → генерує локальною моделлю → пише доку зі **свіжим CRC** (і degraded-маркером,
якщо не дотягнула) → друкує прогрес і підсумок.

Повʼязані тести визначаються за relative reference, який резолвиться у source (`import`,
`require`, dynamic import, `vi.mock` тощо), плюс naming/layout evidence (`foo.test` → `foo`
або `module/tests/*` → module `main`/`index`). Shared test helpers, які тест лише імпортує,
не стають evidence. JS детерміновано рендерить один компактний рядок на test-файл: до двох
груп, пʼять дослівних прикладів і точний лічильник решти; test-код і сценарії не потрапляють до
моделі. Зміна такого тесту робить source-доку stale.

Авторські коментарі теж є першоджерелом: для JSDoc, rustdoc і Python docstring-ів JS дослівно
збирає «Огляд» і «Публічний API». Детальний наратив дає `comment-only` (0 LLM); короткий
pointer або складний flow — `comment+behavior`, де LLM дописує тільки «Поведінку», а judge
перевіряє лише її. За неповних коментарів лишається звичайний `fallback`.

### Крок 2: Підтвердження

Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
preflight). Degraded — не помилка: дока існує, CRC свіжий.

## Правила стилю документа (за єдиною doc-files policy)

- Мова — **УКРАЇНСЬКА** для всього тексту. Code identifiers, шляхи, імена API, команди — як у коді.
- **Чистий Markdown.** Жодних HTML-обгорток. Єдиний виняток — машинний `docgen:`-frontmatter із CRC.
- **Фокус на ПОВЕДІНЦІ, не реалізації.** ЩО і НАВІЩО, а не як саме зроблено.
- Не перелічуй модулі стандартної бібліотеки і внутрішні назви допоміжних функцій.
- Кожна секція самодостатня (без «як вище», «ця функція»).
- Секції (лише доречні): `## Огляд`, `## Поведінка`, `## Публічний API`, `## Де використовується`,
  `## Гарантії поведінки`; для `.vue` — `## Інтерфейс компонента`.
- Не вигадуй деталей, яких немає в коді.

## Нотатки

- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
- Scanner не створює окремих док для `*.test.*` / `*.spec.*`, але використовує повʼязані
  тести як evidence для source-доки. Він ігнорує `node_modules`, `dist`, `.git`,
  `__pycache__`, `coverage`, `.cursor`, `.claude`, усі теки `docs/` і `*.d.ts`.
  Кореневий repo `docs/` — system-wide only: file-level docs туди не пишуться. Список
  glob-ів — `docgen-ignore.mjs`.
- Package-level business/architecture documentation належить цій самій `doc-files`
  surface, але має окремий atomic CLI workflow: `n-rules docs domains`, `n-rules docs
  build --domain <id>` і explicit `--publish`. File-level lint не публікує domain
  projections автоматично.