check-readme-sync: warn on EN vs translated README bold-link roster drift - #18
Open
sergiobuilds wants to merge 1 commit into
Open
check-readme-sync: warn on EN vs translated README bold-link roster drift#18sergiobuilds wants to merge 1 commit into
sergiobuilds wants to merge 1 commit into
Conversation
…-link SET+ORDER (warn-first) The English README's skill roster (bold-link **[name](path) entries) is the source of truth for the 10 localized copies under docs/readme/. CLAUDE.md's shipping checklist step 2 already requires translations track the English roster, but there is no automation — this script fills that gap. Scope is intentionally narrow: SET (each translation contains every EN skill) and ORDER (shared-subset order matches EN). Translated prose, tone, and completeness are left to maintainer judgment. The 'guards the set, not the order' carve-out from check-catalog-sync applies to the four internal roster surfaces (plugin.json / catalog.cjs / re0-upgrade / EN README) which the maintainer holds by hand; localized READMEs sit outside that boundary because they are downstream mirrors of the EN README, not peers of it. Default is warn-only (exit 0) so a translation lag never blocks CI or a merge; pass --strict to promote it to a failure once the maintainer wants enforcement. Wired into ci.yml as a warn-only step and referenced from CLAUDE.md alongside check-catalog-sync. tests/check-readme-sync.test.cjs covers normal, missing, order-swap, and --strict cases with a temp-dir fixture repo. Current state on main: all 10 translations pass. The check is preventive. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
~100줄 스크립트 하나(
scripts/check-readme-sync.cjs)로, 루트README.md의 skill 볼드 링크(**[<skill>](path)) 로스터와docs/readme/README.<lang>.md10개 번역본의 로스터를 비교합니다. SET(누락)과 ORDER(공통 부분집합의 순서 일치)를 검증합니다. 기본은 warn-only.Why
CLAUDE.md의 shipping checklist step 2가 이미 "번역본도 함께 갱신한다"고 요구하고 있는데 자동화가 없었습니다. 번역본은
ba9ae6e feat: add localized READMEs이후 콘텐츠 갱신 없이16a98c3에서 스위처 정규화만 받았고, 그동안 EN 쪽은 여러 번 skill이 추가·개명됐습니다. 현재 시점(cdbb4a1b)에는 볼드 링크 로스터가 우연히 정렬돼 있어 이 PR은 예방용입니다.check-catalog-sync는 4개 내부 surface(plugin.json / catalog.cjs / re0-upgrade / EN README)의 SET만 지키고 ORDER는 사람 판단으로 남겨뒀습니다. 그 결정을 존중해서, 이 스크립트는 EN README를 downstream mirror인 번역본에만 적용합니다. 4-surface 사이에는 손대지 않습니다.Scope
--strict로 exit 1 승격.Wiring
.github/workflows/ci.yml에Localized README bold-link roster drift-guard (warn-only)스텝 한 줄 추가.CLAUDE.mdshipping step 2에check-readme-sync를 언급하고, warn-only 기본과--strict승격 옵션을 명시.package.json은 손대지 않았습니다(현재scripts필드가 비어 있고, 다른 check-* 도구도 CI에서 직접 호출하는 스타일이라 그 관습을 따랐습니다).Test
tests/check-readme-sync.test.cjs— temp 디렉토리에 합성 저장소를 만들어 4개 케이스:1 missing (readchk)리포트order mismatch리포트::error::출력로컬 실측: 현재 main(cdbb4a1)에서
node scripts/check-readme-sync.cjs는README sync OK: 28 bold-link skills match across 10 localizations을 반환합니다.Notes
--strict로 승격하거나 CI 스텝을 그대로 fail-mode로 바꾸면 됩니다.