chore(engines): define NeMo supported version policy and smoke-gate strategy

Background

PR #323 (Issue #321 PR #2) で Canary / Parakeet の NeMo fallback chain (Path 2/3 + return_hypotheses=True TypeError fallback) を削除、framework contract を trust する方針に整理しました。同 PR plan で「nemo-toolkit version contract は >=2.3.0,<2.5.0 を維持」と決定しましたが、これは 暗黙的な policy として PR 内に残しており、project-level の明示的な policy ドキュメントは未整備です。

最近の cleanup 群 (PR #320 / PR #322 / PR #323 / PR #325 / PR #329) で「silent fallback を残さず hard fail」方針が固まったため、NeMo 互換性を smoke gate に委ねる という選択を取った以上、policy を明文化する必要があります。

要検討論点

1. nemo-toolkit>=2.3.0,<2.5.0 の根拠

pyproject.toml:83 の現行 range:

"nemo-toolkit>=2.3.0,<2.5.0",  # 2.1.0 has canary transcription bug (empty output)

• 下限 2.3.0: Canary return_hypotheses=True 安定動作 (#311 PR-A.4.2 で verify、2.1.0 は canary transcription bug で除外)
• 上限 <2.5.0: 上限の 根拠が PR 内 plan に明文化されておらず、暗黙的

→ 論点: 上限 <2.5.0 の根拠を実機 verify して明文化すべきか? それとも保守的に <2.5.0 を維持か?

2. lockfile (uv.lock) pinned vs version range の関係

• uv.lock の pinned 2.3.0 が CI smoke の実行基準
• user の uv sync で <2.5.0 の最新 (例: 2.4.x) も install されうる
• CI smoke は 2.3.0 のみ verify、2.4.x で動かなくなる risk あり

→ 論点:

• (a) 「対応保証 = pinned (==2.3.0)」を明示、range は緩めに残す → user 自己責任
• (b) 「range 内なら動く」を主張、上限/下限の境界で smoke を回す
• (c) lockfile pinned を contract として CI smoke で verify、range は「動作期待 (未保証)」とする (現状の暗黙 policy)

3. CI smoke gate の役割

PR #323 で engine-smoke-gpu job が merge gate 化、test_token_confidence_populated で 3 case verify:

Case	Expected token_confidence_mean
canary_gpu_en	> 0.05 (PR-A.4.2 baseline 0.0724)
parakeet_gpu_en	> 0.10 (PR-A.4.3 baseline 0.2452)
parakeet_ja_gpu_ja	> 0.02 (PR-A.0 baseline 0.0504)

→ 論点:

• 上限 nemo (2.4.x) で smoke を回す runner を追加するか?
• 上限 nemo が動かなくなった時の検知方法は? (現状: user 報告か、scheduled CI で発覚)
• Renovate / Dependabot 導入の是非

4. Version bump 手順

新 nemo バージョン採用時の決定 flow:

• (a) 個別 PR で pyproject.toml 上限拡大 + smoke 実機 verify (manual review)
• (b) Scheduled CI で latest nemo を試行、failure 時に notification
• (c) GitHub Dependabot auto-PR (smoke gate が pass すれば auto-merge)
• (d) (現状) 暗黙的、必要な時に PR で対応

→ 論点:

• どの方針を採るか?
• 上限拡大時の必要 verification は何か? (smoke 3 case pass 以外に必要なものは?)
• 上限 nemo で confidence threshold が下がった (例: 0.0724 → 0.04) ような subtle regression を検知する仕組みは必要か?

5. Fallback を増やさない方針の継続

PR #323 で削除した Path 2/3 (silent degradation 源) を、将来の nemo update 時に「互換のため再 introduce」しない原則を明文化:

• 新 nemo で change_decoding_strategy(confidence_cfg=...) が rejected → fallback を増やさず、上限を <X.Y に下げる (= 互換性を broken と判断、nemo bump を delay)
• return_hypotheses=True が deprecated → API 削除と判断、対応 nemo 上限を更新 (= silent fallback を増やさない)

→ 論点: この原則を docs/development/nemo-version-policy.md (新規) と CLAUDE.md の Backward Compatibility Policy section に link で明文化するか?

提案する Policy 文書化

新規ファイル: docs/development/nemo-version-policy.md

以下 5 sections で構成:

1. 対応 range の現状 (>=2.3.0,<2.5.0) と各 boundary の根拠 (下限 = canary bug、上限 = 要 verify)
2. 動作保証 level:
   • pinned (uv.lock 2.3.0) = fully guaranteed by CI smoke
   • range (<2.5.0 内の他 version) = 動作期待、未保証
3. CI smoke gate の役割: PR-A.4.2/A.4.3/A.5.2 で確立した confidence populate verify (3 case + per-case threshold)
4. Version bump workflow: 誰が trigger、何を確認、どこに記録 (PR title prefix chore(deps): bump nemo-toolkit to X.Y 等の convention)
5. Fallback addition の禁止原則: 互換目的の silent fallback は復活させない (PR #323 precedent 通り、上限を下げて互換切れを宣言する方を選ぶ)

Update: AGENTS.md / CLAUDE.md

NeMo 関連の判断で本 policy doc を reference するよう add link section。

Scope

IN scope (本 issue 実装時)

• docs/development/nemo-version-policy.md 新規作成、上記 5 section
• AGENTS.md または CLAUDE.md から policy 文書への link 追加
• (option) pyproject.toml:83 の comment で >=2.3,<2.5 の根拠を明文化 (現状 comment は下限のみ言及)

OUT scope

• 実際の nemo version bump (本 issue は policy 整備のみ)
• Renovate / Dependabot 導入 (別議論)
• 他 framework (transformers / torch / sherpa-onnx) の version policy (本 issue は NeMo 限定)
• 上限 nemo (2.4.x) での実機 verify (実装段階で必要なら別 PR)

Acceptance criteria (実装段階)

• 論点 1-5 すべてに決定: 本 issue を policy 化する前に、design 決定を本 issue comment に明記
• docs/development/nemo-version-policy.md 新規作成、5 sections を明記
• 下限 >=2.3.0 の根拠 (canary bug avoidance) を git history / PR #311 へ link
• 上限 <2.5.0 の根拠を実機 verify して明文化、または「保守的上限、未 verify」を明示
• CI smoke gate の役割 (PR #323 の test_token_confidence_populated) を policy 文書から reference
• AGENTS.md または CLAUDE.md から policy 文書への link 追加
• PR #323 で確立した「fallback を増やさない」原則を CLAUDE.md「Backward Compatibility Policy (pre-1.0)」の補足として記述

Related

• 起点: PR #323 (NeMo fallback chain cleanup、本 issue で policy 化が必要と判断された場)
• precedent (framework-trust 方針): PR #320 commit ee1d2c1、PR #322、PR #325
• related cleanup: PR #329 (Issue #326 SharedEngineManager orphan 削除)
• 関連 file:
  • pyproject.toml:83 — nemo-toolkit>=2.3.0,<2.5.0 (本 issue の対象 range)
  • uv.lock — pinned nemo-toolkit==2.3.0 (現状の CI smoke 実行 version)
  • tests/integration/engines/test_smoke_engines.py::test_token_confidence_populated — PR #323 で導入した merge gate (本 issue policy で reference 予定)

Read pyproject.toml:83, uv.lock, tests/integration/engines/test_smoke_engines.py::test_token_confidence_populated, and the related PRs before resolving the five policy decisions in the issue. Then create docs/development/nemo-version-policy.md and add references in AGENTS.md or CLAUDE.md. Done means the decisions, version guarantees, smoke-gate role, bump workflow, and no-fallback principle are documented with the requested links.