feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1）

[akiojin]

Summary

• Add unity-cli reference subcommand family and unity-csharp-reference skill so LLMs and developers can browse the official Unity C# source (UnityCsReference) as a read-only local cache when implementing Unity scripts.
• Establish a per-Unity-version cache layout under ~/.unity/cache/UnityCsReference/<version>/ driven by ProjectVersion.txt detection plus a static branch map.
• Land the SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 Phase 1 scope only; Phase 2 (symbol lookup index) and Phase 3 (cross-version diff / LSP integration) will be tracked as separate SPECs.

Changes

• src/reference/version.rs: parse ProjectSettings/ProjectVersion.txt, map major.minor to UnityCsReference branches (2020.3/staging through 6000.0/staging), surface --branch hint for unmapped versions.
• src/reference/cache.rs: reference_root, version_dir, read_meta / write_meta (.unity-cli-meta.json), list_versions, and gc(keep, dry_run) for LRU-by-mtime cleanup.
• src/reference/fetcher.rs: build_clone_args (--depth 1 --single-branch --branch <ver>), license gate (--accept-license / UNITY_CLI_ACCEPT_LICENSE=1), git availability probe, GITHUB_TOKEN / GH_TOKEN injection via http.extraHeader.
• src/reference/search.rs: run_grep (walkdir + regex with optional file-name glob and context lines) and run_view (line range slice, .. traversal guard).
• src/reference/mod.rs: maybe_execute_reference_tool JSON dispatcher for reference_fetch / reference_status / reference_search / reference_grep / reference_view / reference_clean.
• src/cli.rs and src/app/runner.rs: Command::Reference plus ReferenceCommand and build_reference_call helper routing each subcommand to execute_tool("reference_*", params).
• src/tooling/tool_catalog.rs and src/tooling/local_tools.rs: register reference_* 6 tools, mark them ToolExecutor::Local, classify fetch/clean as mutating and status/search/grep/view as read-only, define per-tool params_schema, and delegate from maybe_execute_local_tool.
• src/core/managed_binaries.rs: add cache_root() (env override via UNITY_CLI_CACHE_ROOT, defaults to ~/.unity/cache).
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-reference/: new skill (SKILL.md + references/{runtime-checklist,fetch-and-cache,symbol-lookup-playbook}.md) under Skill Contract v1. .claude/skills/unity-csharp-reference and .agents/skills/unity-csharp-reference symlinks added for discovery.
• .claude-plugin/plugins/unity-cli/skills/unity-csharp-{edit,navigate}/SKILL.md and unity-scene-inspect/SKILL.md: cross-list unity-csharp-reference in siblings to clear R12 / R22 collisions.
• docs/tools.md, README.ja.md, ATTRIBUTION.md: new Reference Cache section, README feature line, and Unity Companion License attribution (English + Japanese).
• tests/fixtures/reference-cache/: minimal fixture (Editor + Runtime/Export/Animation) used by grep / view snapshot tests.

Testing

• cargo fmt -- --check — clean (no diff)
• cargo clippy --all-targets -- -D warnings — clean
• cargo test --bin unity-cli — 278 passed, 0 failed (19 new tests across reference modules)
• unity-cli skills lint --severity error — 15 skills checked, 0 violations
• CLI smoke: UNITY_CLI_CACHE_ROOT="$(mktemp -d)" unity-cli reference status --output json → { "ok": true, "versions": [] }

Closing Issues

• Closes feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185

Related Issues / Links

• None (Phase 2 / Phase 3 follow-up SPECs will be filed after this lands)

Checklist

• Tests added/updated
• Lint/format passed (cargo clippy, cargo fmt, unity-cli skills lint)
• Documentation updated (docs/tools.md, README.ja.md, ATTRIBUTION.md, new skill)
• Migration/backfill plan included — Not applicable: no schema or data change.
• CHANGELOG impact considered — minor bump per Conventional Commits (feat)

Context

• unity-cli previously gave LLMs access only to project-local C# sources and csharp-lsp (OmniSharp/Roslyn) metadata when implementing Unity scripts. The official Unity C# implementation was unreachable, so API misuse, behavior assumptions, and version-specific differences had to be guessed.
• SPEC feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 (gwt-spec) was filed after a gwt-discussion session decided to mirror UnityCsReference locally as a read-only cache exposed through unity-cli reference and a sibling unity-csharp-reference skill.

Risk / Impact

• Affected areas: new src/reference/ module + CLI / catalog / local dispatcher wiring; new skill alongside existing unity-csharp-{navigate,edit} / unity-scene-inspect (siblings cross-listed). Cache lives under ~/.unity/cache/UnityCsReference/<version>/ and is independent of ~/.unity/tools/ (managed_binaries). LSP workspace folders are intentionally untouched to avoid rename/diagnostic noise from external sources.
• Disk footprint: shallow clones land at roughly 400-600 MB per Unity version. reference clean --keep 1 is the default knob; reference status --output json surfaces sizeBytes.
• License: cached source is under Unity Companion License. Fetch is hard-gated by --accept-license or UNITY_CLI_ACCEPT_LICENSE=1; ATTRIBUTION.md documents the consent and no-redistribution rule.
• Rollback plan: revert this commit. The reference cache directory can be removed safely (rm -rf ~/.unity/cache/UnityCsReference). No persisted state outside that directory.

Notes

• Phase 2 (symbol lookup index, reference find-symbol) and Phase 3 (cross-version diff + LSP go-to-definition experiment) are intentionally out of scope and will be tracked as follow-up SPECs.
• The Issue feat(reference): UnityCsReference のローカルキャッシュ参照機構（Phase 1） #185 build report comment (4420282211) captures the T1-T17 task-level evidence for reviewers.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: fd49a3f5-0909-4758-b7c7-ed92ba896961

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch work/20260511-0223

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[akiojin]

CI gate clear: merge_state CLEAN

gwt-manage-pr fix mode で発見された 2 系統の blocker を解消し、CI を緑にしました。

修正サマリ

• Rust Format & Lint (clippy 1.95): src/app/runner.rs 内の collapsible_match 3 件を match guard に書き換え、src/reference/cache.rs の sort_by を sort_by_key(Reverse(_)) に書き換え。追加 test 内の未使用 tool を _tool に、#[allow(clippy::await_holding_lock)] の位置を run_with_cli_set_active_text_output_when_reachable に正しく戻した。
• Rust Coverage >= 90% (required): reference 系 / core/self_update.rs / core/managed_binaries.rs / app/runner.rs::build_reference_call に計 60+ 件のユニットテストを追加し、ローカル cargo llvm-cov --all-targets 計測で TOTAL 89.15% → 90.44%。CI でも >= 90% を pass。

現在の CI 状態

• Rust Format & Lint: SUCCESS
• Rust Tests / LSP Tests / LSP Performance: SUCCESS
• Rust Coverage / LSP Coverage (>= 90%): SUCCESS
• Skill Contract Lint / Markdown & Commitlint / CodeRabbit: SUCCESS
• mergeable: MERGEABLE, merge_state: CLEAN

レビューおよび merge をお願いします。Phase 2 (シンボル lookup インデックス) と Phase 3 (バージョン差分 + LSP go-to-definition 実験) は別 SPEC として後続で切り出します。