opencode-voice-dictation/docs/decisions/0006-pr-39-align-readme-checker.md

ADR 0006: Align README with updated create-readme checker

• Date: 2026-07-30
• PR: 39
• Issue: #38

Статус

Accepted.

Контекст

Тулза create-readme (в slaid098/opencode-config) обновилась серией коммитов и PR (#149, #151, #153, aa48fd7): новые требования валидатора — tagline_en/tagline_ru как обязательные параметры с собственными delimiter-тегами <!-- tagline-en:start/end --> и <!-- tagline-ru:start/end -->, H1 title с prefix # 🚀 , блок ручного заголовка ## License/## LICENSE/## Лицензия как ERROR (дубликат GitHub sidebar). README, сгенерированный в PR #37 (ADR 0005), использует старый стандарт — один общий tagline без delimiter-тегов — и не прошёл бы новый validate (Missing <!-- tagline-en:start --> delimiter, Missing <!-- tagline-ru:start --> delimiter).

Баг #148 в create-readme (create mode не перезаписывает существующий локальный README через fs.writeFileSync — git status пуст после вызова, mtime не меняется) делает локальную перегенерацию невозможной. Remote-режим тулзы (repo: owner/name) обходит #148 (пишет через gh api PUT с base64+SHA), но пишет напрямую в default branch (main), минуя PR-процесс — неприемлемо для ревью-флоу.

Решение

Перегенерировать README по новому стандарту вручную по шаблону skill repo-readme §5, обойдя баг #148 через ручную сборку + validate.

1. Сначала протестирован локальный режим create-readme (mode: create, без repo). Вызов с полным набором параметров нового стандарта (tagline_en/tagline_ru, why_en/what_en, why_ru/what_ru, features_en/features_ru, include_clone: false, quick_start: "", quick_start_steps_en/quick_start_steps_ru). Тулза вернула успех, но git diff пуст, ls -la README.md mtime не изменился — баг #148 подтверждён на этом репо.

2. Ручная сборка README по шаблону SKILL.md §5. README.md пересобран через Write с точной структурой нового стандарта: H1 # 🚀 opencode-voice-dictation, две пары tagline-en/tagline-ru delimiter-тегов (новое, отсутствовало в PR #37), четыре пары summary-en/features-en/summary-ru/features-ru (уже были), language switcher [English](#-english) | [Русский](#-русский), Quick Start / Быстрый старт (4 кликабельных шага каждый, без bash-блока — include_clone: false + quick_start: ""), секция ## 💬 Support and contacts. Секция ## License отсутствует (блокируется новым чекером как дубликат GitHub sidebar). Контент tagline/why/what/features идентичен параметрам, переданным в create-readme.

3. create-readme (mode: validate) прошёл. ✅ README structure is valid — все 6 пар delimiter-тегов (tagline + summary + features × EN/RU) присутствуют, H1 prefix корректен, support-ссылка на месте, License-секции нет.

4. Diff минимален. Только 5 строк добавлено (tagline delimiter-теги + RU tagline), остальной контент уже соответствовал стандарту PR #37. Никакие другие файлы не тронуты (vite.config.ts, src/, tests/, package.json, assets/, .github/, docs/project-map/ — нетронуты).

Альтернативы

1. Remote-режим create-readme (repo: "slaid098/opencode-voice-dictation")

• Плюс: обходит баг #148 (пишет через gh api repos/{owner}/{repo}/contents/README.md PUT с base64+SHA).
• Минус: пишет напрямую в default branch (main) через GitHub API, минуя PR-процесс — нет ревью, нет CI-проверок, прямой коммит на main. Нарушает linear pipeline execution (AGENTS.md). Отвергнуто.

2. Ждать фикса бага #148 в create-readme

• Плюс: потом локальный create сработает сам, ручная сборка не нужна.
• Минус: блокирует работу — issue #38 требует выровнять README сейчас (PR #37 README невалиден по новому чекеру). Сроки фикса #148 неизвестны. Отвергнуто.

3. Оставить старый README (из PR #37) без tagline delimiter-тегов

• Плюс: ноль работы.
• Минус: не прошёл бы новый validate (Missing <!-- tagline-en:start --> delimiter). Витрина slaid098.dev не сможет распарсить tagline для карточки. Отвергнуто.

Последствия

• README теперь соответствует новому стандарту create-readme (6 пар delimiter-тегов: tagline-en/ru + summary-en/ru + features-en/ru). Витрина slaid098.dev парсит все 6 фрагментов — tagline EN/RU для карточки, summary/features для деталей.
• validate проходит. Будущие правки README должны сохранять все 6 пар delimiter-тегов — после ручных правок обязательна re-валидация через create-readme (mode: validate).
• Баг #148 остаётся открытым — локальный create всё ещё не перезаписывает существующий README. Workaround (ручная сборка + validate) задокументирован здесь, применим для будущих PR пока #148 не пофикшен.
• Никакие runtime-файлы не затронуты — изменение чисто документационное, CI/сборка/userscript-раздача не меняются.
• ADR 0006 + handoff созданы. Placeholder <PR-NUMBER> в frontmatter заменён на реальный номер после create-pr (отдельный коммит docs(handoff): set PR number).

Источники

• README.md (до/после) — diff: +5 строк (tagline-en/ru delimiter-теги)
• Skill repo-readme SKILL.md §5 — шаблон README с delimiter-тегами
• Skill repo-readme SKILL.md §9 — breaking change: tagline → tagline_en + tagline_ru
• create-readme tool — mode: create (локальный режим, баг #148 подтверждён), mode: validate (проходит)
• Issues (вне scope): #147 (create-readme quick_start "" validation — пофикшен, bash-блок не рендерится), #148 (create-readme create не перезаписывает локальный README — обход через ручную сборку)
• PR #37 / ADR 0005 — предыдущая регенерация README (старый стандарт, без tagline delimiter-тегов)
• Issue: #38