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

pr_number	branch	issue	title	status	created
39	docs/align-readme-checker	38	align README with updated create-readme checker	open	2026-07-30

Handoff — PR 39: align README with updated create-readme checker

Что сделано

Один логический коммит на ветке docs/align-readme-checker (планируется второй после получения PR-номера для фикса placeholder):

• docs(readme): regenerate README with tagline_en/ru delimiters — README.md пересобран по новому стандарту create-readme (skill repo-readme §5): добавлены две пары delimiter-тегов <!-- tagline-en:start -->/<!-- tagline-en:end --> и <!-- tagline-ru:start -->/<!-- tagline-ru:end --> с EN/RU tagline (новое требование из #149, #151, #153, aa48fd7 — отсутствовало в PR #37). Существующие 4 пары summary-en/features-en/summary-ru/features-ru сохранены. H1 # 🚀 opencode-voice-dictation (prefix корректен). Quick Start / Быстрый старт — по 4 кликабельных шага, без bash-блока (include_clone: false + quick_start: ""). Секция ## License отсутствует (блокируется новым чекером как дубликат GitHub sidebar). create-readme (mode: validate) проходит: ✅ README structure is valid. Diff: +5 строк (только tagline-теги), остальной контент уже соответствовал PR #37.

• docs(repo): add ADR and handoff for readme alignment — docs/decisions/0006-pr-39-align-readme-checker.md (ADR 0006: Статус/Контекст/Решение/Альтернативы/Последствия/Источники) + этот handoff. Placeholder <PR-NUMBER> в frontmatter и заголовках заменён на реальный номер 39 коммитом docs(handoff): set PR number после create-pr.

Workaround бага #148 (create-readme create mode не перезаписывает существующий локальный README): локальный create вызван с полным набором параметров нового стандарта — тулза вернула успех, но git diff пуст, mtime не изменился (bug подтверждён). README собран вручную через Write по шаблону SKILL.md §5, затем validate прошёл. Remote-режим (repo:) НЕ использовался — пишет напрямую на main, минуя PR-процесс.

Почему

• Тулза create-readme обновилась. PR #149, #151, #153, aa48fd7 в slaid098/opencode-config: tagline → tagline_en + tagline_ru (breaking change, SKILL.md §9), новые обязательные delimiter-теги <!-- tagline-en:start/end --> / <!-- tagline-ru:start/end -->, H1 prefix # 🚀 валидируется, ручной заголовок ## License/## LICENSE/## Лицензия флагируется как ERROR (дубликат GitHub sidebar).
• README из PR #37 невалиден по новому чекеру. Один общий tagline без delimiter-тегов → Missing <!-- tagline-en:start --> delimiter + Missing <!-- tagline-ru:start --> delimiter. Витрина slaid098.dev не парсит tagline для карточки.
• Баг #148 блокирует локальную перегенерацию. create-readme create mode не перезаписывает существующий локальный README (fs.writeFileSync не срабатывает для существующего файла, mtime/diff пустые). Workaround — ручная сборка по шаблону + validate.
• Remote-режим неприемлем. create-readme с repo: owner/name пишет через gh api PUT напрямую в default branch (main), минуя PR-процесс — нет ревью, нет CI. Нарушает linear pipeline execution (AGENTS.md).

Pending

• После merge: проверить витрину slaid098.dev — карточка opencode-voice-dictation должна подтянуть tagline EN/RU из нового README (между <!-- tagline-en:start -->/<!-- tagline-ru:end -->). Раньше tagline не парсился (delimiter-тегов не было).
• После merge: запустить create-readme (mode: validate) на fresh main — должен пройти (проверка, что merge не нарушил структуру).
• Issue #148 (create-readme create не перезаписывает локальный README) — остаётся открытым. Workaround (ручная сборка + validate) задокументирован в ADR 0006, применим для будущих PR пока #148 не пофикшен.
• Placeholder <PR-NUMBER> в docs/decisions/0006-pr-39-align-readme-checker.md (filename + frontmatter + заголовок) и в этом handoff (frontmatter + заголовок + body) заменён на реальный PR-номер 39 коммитом docs(handoff): set PR number после create-pr, затем push.

Watch out

• validate парадоксально проходит на README БЕЗ tagline-тегов. При тестировании обнаружено: текущий README (до правок) проходил validate несмотря на отсутствие <!-- tagline-en:start --> — тулза валидирует наличие delimiter-пар, но tagline-теги НЕ были обязательны в момент предыдущего вызова (возможно кеш версии тулзы или валидатор проверяет 4 пары, а не 6). После ручной сборки по шаблону с tagline-тегами validate также проходит — структура теперь гарантированно соответствует SKILL.md §5. Не полагаться на "validate проходит" как признак соответствия новому стандарту — проверять наличие всех 6 пар delimiter-тегов вручную через grep -c "tagline-en\|tagline-ru\|summary-en\|summary-ru\|features-en\|features-ru".
• Баг #148 воспроизводим. create-readme (mode: create, локальный, без repo) вернул "README.md created at README.md" но git diff пуст, mtime не изменился. Тулза НЕ падает — молча не пишет. Диагностика: ls -la README.md до/после (mtime) + git diff --stat README.md. Если mtime/diff пустые — баг #148, переход на ручную сборку по шаблону SKILL.md §5.
• Изменение чисто документационное. Никакие runtime-файлы не затронуты (vite.config.ts, src/, tests/, package.json, assets/, .github/, docs/project-map/). CI/сборка/userscript-раздача через dist не меняются. PR должен пройти lint/typecheck/test без проблем.
• Default branch — main, не master. В задании упоминался master, но в slaid098/opencode-voice-dictation default branch main (проверено git symbolic-ref refs/remotes/origin/HEAD). Ветка создана от origin/main.