agentleFS
ayutazayutaz/piper-plus/.claude/skills/check-loanword/SKILL.md

check-loanword

Skill240 starsChanged 5 days agoMITView on GitHub

ZH-EN code-switching loanword の同期と forward-compat を 1 コマンドで検査。`docs/spec/loanword-mirrors.toml` に定義された runtime 10 mirror と fixture 8 mirror を確認する。

The file

Files
SKILL.md

ZH-EN Loanword Consistency Check

ZH-EN code-switching (Issue #384) で使う loanword 辞書 (zh_en_loanword.json) の同期チェック。Python source を 唯一の真実 とし、docs/spec/loanword-mirrors.toml の 10 runtime mirror + 8 fixture mirror が一致することを保証する。

何をチェックするか

docs/reference/zh-en-loanword/README.md の不変条件:

  1. 10 mirror byte-for-byte sync — Python source と以下の mirror が SHA256 一致:
    • Python runtime (src/python_run/piper_plus/phonemize/data/zh_en_loanword.json)
    • Rust 2 crate (src/rust/piper-plus-g2p/data/, src/rust/piper-core/data/)
    • Go (src/go/phonemize/data/zh_en_loanword.json)
    • C# (src/csharp/PiperPlus.Core/Phonemize/Data/zh_en_loanword.json)
    • WASM (src/wasm/g2p/data/zh_en_loanword.json)
    • C++ (src/cpp/data/zh_en_loanword.json)
    • Kotlin Android (android/piper-plus-g2p/src/main/assets/zh_en_loanword.json)
    • Swift G2P (Sources/PiperPlusG2P/Resources/zh_en_loanword.json)
  2. Schema validation — Python の _load_loanword_data と同じ書式 ('<section>.<key>' must be list[str]) でエラーを出すこと
  3. 8 fixture mirror sync — tests/fixtures/g2p/zh_en_loanword_matrix.json と以下の mirror が一致:
    • src/go/phonemize/testdata/
    • src/csharp/PiperPlus.Core.Tests/Phonemize/TestData/
    • src/cpp/tests/fixtures/
    • src/wasm/g2p/test/fixtures/
    • src/rust/piper-plus-g2p/tests/fixtures/, src/rust/piper-core/tests/fixtures/
    • android/piper-plus-g2p/src/androidTest/assets/g2p_fixtures/
    • tests/PiperPlusG2PTests/Fixtures/
  4. Forward-compat (YELLOW-5) — 各ランタイムの loader が schema_version: 2 未来の追加フィールドを silent ignore すること

実行ステップ

1. ローカルで sync 状態を確認

python scripts/check_loanword_consistency.py

期待: OK All 17 mirror(s) in sync across 2 group(s) で終了 (exit 0)。

2. drift 発見時は自動修復

Python source を canonical とした 一方向コピー で復元:

python scripts/check_loanword_consistency.py --diff   # 差分確認 (dry-run)
python scripts/check_loanword_consistency.py --fix    # 10 mirror + 8 fixture を Python source に揃える

注意: Mirror を直接編集しても --fix で上書きされる。JSON 変更を提案する場合は 必ず Python source (src/python/g2p/piper_plus_g2p/data/zh_en_loanword.json) を編集 すること。

3. Schema validation のみ確認 (CI 用)

python scripts/check_loanword_consistency.py --schema-only

4. 各ランタイムの forward-compat loader test を回す

各ランタイムに *Loader*Schema*V2* 系の test が存在し、未来の schema_version: 2 を受理することを pinning している:

# Rust (両 crate)
cd src/rust && cargo test test_zh_en_loader_accepts_unknown_fields_in_schema_v2

# Go
cd src/go && go test ./phonemize/... -run TestLoaderAcceptsUnknownFieldsInSchemaV2

# C#
cd src/csharp && dotnet test --filter "FullyQualifiedName~Loader_AcceptsUnknownFieldsInSchemaV2"

# WASM
node --test src/wasm/g2p/test/test-chinese-zh-en.js  # forward-compat assertion 含む

5. CI workflow が green か確認

gh workflow view "ZH-EN Loanword Sync Gate" --branch <branch>

json-sync job (5 分以内) が PASS していれば OK。

確認すべき事項

  • python scripts/check_loanword_consistency.py が OK All 17 mirror(s) in sync across 2 group(s) を返す
  • schema validation でエラーなし
  • spec に定義された各 runtime の forward-compat loader test が PASS
  • CI workflow ZH-EN Loanword Sync Gate / json-sync が green
  • git diff src/python/g2p/piper_plus_g2p/data/zh_en_loanword.json が意図した変更のみ
  • PR description に "loanword JSON updated, mirrors auto-synced via --fix" を明記

トラブルシューティング

症状対処
MISMATCH src/.../zh_en_loanword.json--fix で復元、または Python source の意図しない変更を revert
MISSING src/.../zh_en_loanword.json--fix で作成、または該当ランタイム実装が未着手 (Phase 6a 想定なら --allow-missing を一時利用)
'acronyms.GPS' must be list[str]Python source で値型が間違っている。["ji4", "pi4", "ai1", "si4"] の形式に修正
FIXTURE OUT OF SYNCtests/fixtures/g2p/zh_en_loanword_matrix.json を更新後 --fix で 8 fixture mirror に展開
Windows で sha256 不一致が常時出る.gitattributes の *.json text eol=lf で CRLF 強制 LF。再正規化: git rm --cached <file> && git add <file>

関連ドキュメント

  • ZH-EN runtime rollout 設計書
  • Cross-runtime fixture matrix
  • Workflow
  • PUA sync skill (template)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.